docs: clarify indexeddb adapter architecture and add json/prepared capabilities

- Updated all docs to clarify IndexedDB adapter is sql.js + IndexedDB persistence wrapper
- Added 'json' and 'prepared' capabilities to IndexedDB and sql.js adapters
- Updated README, PLATFORM_STRATEGY, and ARCHITECTURE docs
- Version bump to 0.3.2

Author: jddunn

CHANGELOG.md

@@ -5,10 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] - 2025-11-07
+
+### Changed
+- **Documentation clarifications**: Updated all docs to clarify that IndexedDB adapter is sql.js + IndexedDB persistence wrapper (not a separate SQL engine)
+- **Capability updates**: Added `json` and `prepared` capabilities to IndexedDB and sql.js adapters
+  - Both adapters now correctly declare JSON support (via SQLite JSON1 extension)
+  - Prepared statements capability added for both adapters
+- **README updates**: Clarified IndexedDB adapter relationship with sql.js throughout documentation
+
+### Documentation
+- Updated README.md adapter matrix to clarify IndexedDB is sql.js wrapper
+- Updated PLATFORM_STRATEGY.md with detailed explanation of IndexedDB + sql.js architecture
+- Updated ARCHITECTURE.md to note IndexedDB adapter is not a separate SQL engine
+- Added notes about JSON support via SQLite JSON1 extension for IndexedDB/sql.js adapters
+
 ## [0.3.0] - 2025-11-06
 
 ### Added
-- **IndexedDB Adapter** (`IndexedDbAdapter`) - Browser-native SQL storage using IndexedDB with sql.js for full client-side operation
+- **IndexedDB Adapter** (`IndexedDbAdapter`) - sql.js + IndexedDB persistence wrapper for browser-native SQL storage
+  - **Note**: This adapter uses sql.js (WASM SQLite) for all SQL execution and IndexedDB only for storing the database file as a binary blob
   - Automatic persistence to IndexedDB with configurable auto-save intervals
   - Full SQL support via sql.js (SQLite compiled to WebAssembly)
   - Export/import functionality for data portability

PLATFORM_STRATEGY.md

@@ -20,14 +20,16 @@ const storage = await createAgentOSStorage({
 
 | Adapter | Pros | Cons | Best For |
 |---------|------|------|----------|
-| **IndexedDB** (NEW) | ✅ Native browser API<br>✅ Async, non-blocking<br>✅ 50MB-1GB+ quota<br>✅ Structured transactions<br>✅ No WASM overhead | ❌ Complex API (wrapped by sql.js)<br>❌ IndexedDB quotas vary by browser<br>❌ No SQL queries (need sql.js layer) | **Primary choice** for web<br>Offline PWAs<br>Privacy-first apps |
+| **IndexedDB** (NEW) | ✅ Native browser storage API<br>✅ Async, non-blocking<br>✅ 50MB-1GB+ quota<br>✅ sql.js wrapper (full SQL support)<br>✅ Persistent across sessions | ❌ Uses sql.js WASM (500KB load)<br>❌ IndexedDB quotas vary by browser<br>❌ Not a separate SQL engine (sql.js + IDB persistence) | **Primary choice** for web<br>Offline PWAs<br>Privacy-first apps |
 | **sql.js** | ✅ Full SQLite in WASM<br>✅ In-memory fast reads<br>✅ Optional IDB persistence<br>✅ Zero dependencies | ❌ 500KB WASM load<br>❌ Slow writes to IDB<br>❌ Single-threaded | Fallback for web<br>Edge functions |
 | **LocalStorage** | ✅ 5-10MB simple API | ❌ Synchronous (blocks UI)<br>❌ String-only<br>❌ No transactions | ❌ **NOT RECOMMENDED** |
 
-**Winner:** **IndexedDB + sql.js** (our new IndexedDbAdapter)
-- Best of both: native IDB durability + SQL convenience
+**Winner:** **IndexedDB adapter** (sql.js + IndexedDB persistence wrapper)
+- sql.js provides SQL execution (WASM SQLite)
+- IndexedDB provides browser-native persistence (stores SQLite file as blob)
 - Auto-save batching minimizes IDB overhead
 - Works offline, respects privacy
+- **Note:** This is sql.js with IndexedDB persistence, not a separate SQL engine
 
 ---
 

README.md

@@ -37,7 +37,7 @@ The SQL Storage Adapter provides a single, ergonomic interface over SQLite (nati
 
 - **Auto-detected adapters** – `createDatabase()` inspects environment signals and picks the best backend (native SQLite, PostgreSQL, Capacitor, sql.js, **IndexedDB**, memory, etc.).
 - **Capability-aware API** – consistent CRUD, transactions, batching, and event hooks across adapters with runtime capability introspection.
-- **🆕 IndexedDB** – Browser-native persistence with sql.js for full SQL support in PWAs and offline-first apps.
+- **🆕 IndexedDB** – sql.js + IndexedDB persistence wrapper for browser-native, offline-first web apps (uses sql.js for SQL execution, IndexedDB for storage).
 - **Cloud backups & migrations** – built-in backup manager with compression, retention policies, and restore helpers plus migration utilities.
 - **Portable packaging** – optional native dependencies; falls back to pure TypeScript/WASM adapters when native modules are unavailable.
 - **AgentOS-first** – Pre-configured schema, typed queries, and auto-detection for AgentOS deployments.
@@ -145,10 +145,10 @@ See [Platform Strategy Guide](./PLATFORM_STRATEGY.md) for detailed pros/cons and
 
 | Adapter | Package | Ideal for | Pros | Considerations |
 | --- | --- | --- | --- | --- |
-| **🆕 `indexeddb`** | bundled | **Browsers, PWAs** | Browser-native, async, 50MB-1GB+ quota, SQL via sql.js, offline-first | IndexedDB quotas vary, WASM overhead for SQL |
+| **🆕 `indexeddb`** | bundled (sql.js) | **Browsers, PWAs** | sql.js + IndexedDB persistence wrapper, browser-native storage, 50MB-1GB+ quota, offline-first | IndexedDB quotas vary, WASM overhead (sql.js), not a separate SQL engine |
 | `better-sqlite3` | `better-sqlite3` | Node/Electron, CLI, CI | Native performance, transactional semantics, WAL support | Needs native toolchain; version must match Node ABI |
 | `postgres` | `pg` | Hosted or on-prem PostgreSQL | Connection pooling, rich SQL features, cloud friendly | Requires `DATABASE_URL`/credentials |
-| `sqljs` | bundled | Browsers, serverless edge, native fallback | Pure WASM, no native deps | Write performance limited vs native, optional persistence |
+| `sqljs` | bundled | Browsers, serverless edge, native fallback | Pure WASM SQLite, no native deps, optional filesystem persistence | Write performance limited vs native, in-memory by default |
 | `capacitor` | `@capacitor-community/sqlite` | Mobile (iOS/Android, Capacitor) | Native SQLite on mobile, encryption | Requires Capacitor runtime |
 | `memory` | built-in | Unit tests, storybooks, constrained sandboxes | Zero dependencies, instant startup | Non-durable, single-process only |
 
@@ -188,11 +188,15 @@ await adapter.open();
 ```
 
 **Key Features:**
-- ✅ Transactions (via sql.js)
-- ✅ Persistence (IndexedDB)
+- ✅ SQL execution via sql.js (WASM SQLite)
+- ✅ Persistence via IndexedDB (stores SQLite database file as blob)
+- ✅ JSON support (SQLite JSON1 extension: json_extract, json_object, json_array, etc.)
+- ✅ Prepared statements for performance and security
 - ✅ Export/import (Uint8Array SQLite file format)
 - ✅ Auto-save with batching (reduce IDB overhead)
 
+**Note:** IndexedDB adapter is a wrapper around sql.js that adds IndexedDB persistence. It's not a separate SQL engine—it uses sql.js for all SQL operations and IndexedDB only for storing the database file. Since sql.js is full SQLite WASM, it supports all SQLite features including JSON functions, BLOBs, and full-text search.
+
 ## Platform Strategy
 
 See [**PLATFORM_STRATEGY.md**](./PLATFORM_STRATEGY.md) for a comprehensive guide on:

docs/media/ARCHITECTURE.md

@@ -115,7 +115,9 @@ const db = await resolveStorageAdapter({
 
 ### IndexedDB Adapter (Browser-Native)
 
-**Implementation**: sql.js (SQLite WASM) + IndexedDB for persistence
+**Implementation**: sql.js (SQLite WASM) + IndexedDB persistence wrapper
+
+**Important**: This adapter is **not a separate SQL engine**. It uses sql.js for all SQL execution and IndexedDB only for storing the SQLite database file as a binary blob. Think of it as "sql.js with automatic IndexedDB persistence."
 
 **When to use**:
 - **Browser applications** (primary use case)
@@ -247,13 +249,14 @@ const backup = adapter.exportDatabase();  // Uint8Array (SQLite file)
 
 | Feature | IndexedDB Adapter | SQL.js Adapter |
 |---------|------------------|----------------|
-| **Persistence** | ✅ Automatic | ⚠️ Manual (`save()` required) |
+| **SQL Engine** | sql.js (WASM) | sql.js (WASM) |
+| **Persistence** | ✅ Automatic (IndexedDB) | ⚠️ Manual (`save()` required) |
 | **Auto-save** | ✅ Yes (batched) | ❌ No |
 | **Bundle Size** | Same (~500KB) | Same (~500KB) |
 | **Performance** | Same (both use sql.js) | Same |
 | **Use Case** | Production web apps | Prototyping, edge functions |
 
-**Recommendation**: Use **IndexedDB Adapter** for production web apps (automatic persistence). Use **SQL.js Adapter** only if you need manual control over save timing.
+**Key Difference**: IndexedDB adapter is sql.js + automatic IndexedDB persistence wrapper. SQL.js adapter is sql.js with optional manual persistence. Both use the same SQL engine (sql.js).
 
 **Configuration**:
 ```typescript

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/sql-storage-adapter",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Robust cross-platform SQL storage abstraction with automatic fallbacks and runtime detection",
   "type": "module",
   "main": "dist/index.js",

src/adapters/indexedDbAdapter.ts

@@ -1,19 +1,28 @@
 /**
  * @fileoverview IndexedDB Storage Adapter for AgentOS
- * @description Browser-native SQL storage using IndexedDB with sql.js for full client-side operation.
- * Supports transactions, persistence to IndexedDB, and offline-first workflows.
+ * @description Browser-native SQL storage using sql.js (WASM) for SQL execution and IndexedDB for persistence.
+ * 
+ * **Architecture:**
+ * - **SQL Execution**: Uses sql.js (SQLite compiled to WebAssembly) for full SQL support
+ * - **Persistence**: Stores the SQLite database file (as binary blob) in IndexedDB
+ * - **Workflow**: Load DB from IndexedDB → Execute SQL in memory (sql.js) → Save back to IndexedDB
+ * 
+ * **Why this approach?**
+ * - IndexedDB is NOT SQL - it's a NoSQL key-value store
+ * - sql.js provides full SQLite compatibility (transactions, joins, etc.)
+ * - IndexedDB provides durable browser-native persistence
+ * - Together: Full SQL capabilities + browser persistence = best of both worlds
  * 
  * **Use cases:**
  * - Fully client-side AgentOS (no backend needed)
  * - Progressive Web Apps (PWAs)
  * - Offline-capable agents
  * - Privacy-first applications (data never leaves browser)
  * 
- * **Architecture:**
- * - Uses sql.js (SQLite compiled to WebAssembly) for SQL execution
- * - Persists database to IndexedDB for durability across sessions
- * - Auto-saves after each transaction
- * - Supports import/export for data portability
+ * **Performance:**
+ * - Fast reads (in-memory SQL via sql.js)
+ * - Moderate writes (IndexedDB persistence adds ~10-50ms)
+ * - Auto-save batching reduces IDB overhead
  * 
  * @example
  * ```typescript
@@ -67,9 +76,19 @@ const DB_VERSION = 1;
 /**
  * Storage adapter using IndexedDB + sql.js for client-side SQL persistence.
  * 
+ * **How It Works:**
+ * 1. IndexedDB stores the SQLite database file (binary blob) - this is just storage
+ * 2. sql.js (WASM) loads the database into memory and executes SQL - this provides SQL capabilities
+ * 3. After writes, the updated database is saved back to IndexedDB
+ * 
+ * **Why IndexedDB + sql.js?**
+ * - IndexedDB alone: NoSQL key-value store, no SQL support
+ * - sql.js alone: In-memory SQL, but no persistence across sessions
+ * - Combined: Full SQL + browser-native persistence = complete solution
+ * 
  * **Capabilities:**
- * - ✅ Transactions
- * - ✅ Persistence (IndexedDB)
+ * - ✅ Transactions (via sql.js)
+ * - ✅ Persistence (via IndexedDB)
  * - ✅ Full SQL support (via sql.js)
  * - ✅ Export/import
  * - ❌ Concurrent writes (single-threaded)
@@ -92,7 +111,7 @@ const DB_VERSION = 1;
  */
 export class IndexedDbAdapter implements StorageAdapter {
   public readonly kind = 'indexeddb';
-  public readonly capabilities: ReadonlySet<StorageCapability> = new Set(['transactions', 'persistence']);
+  public readonly capabilities: ReadonlySet<StorageCapability> = new Set(['transactions', 'persistence', 'json', 'prepared']);
 
   private SQL: SqlJsStatic | null = null;
   private db: SqlJsDatabase | null = null;

src/adapters/sqlJsAdapter.ts

@@ -37,7 +37,7 @@ export class SqlJsAdapter implements StorageAdapter {
   private filePath?: string;
 
   constructor(private readonly adapterOptions: SqlJsAdapterOptions = {}) {
-    const caps: StorageCapability[] = ['transactions'];
+    const caps: StorageCapability[] = ['transactions', 'json', 'prepared'];
     if (hasFsAccess()) {
       caps.push('persistence');
     }