Dash-Pensieve Bridge

Zero-copy bridge between Dash SQLite WASM and Pensieve particle system using SharedArrayBuffer.

Purpose

Eliminates serialization overhead when syncing reflection data from Dash (SQLite) to Pensieve's particle system by using shared memory buffers.

Architecture

┌─────────────────┐
│  Dash SQLite    │
│  (WASM)         │
└────────┬────────┘
         │ Query Results
         ▼
┌─────────────────┐
│  Bridge WASM    │ ──► Direct memory write
│  (Zero-copy)    │     to SharedArrayBuffer
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  SharedArray    │ ◄─── Shared memory
│  Buffer         │      (both can access)
└────────┬────────┘
         │
         ├──► Pensieve Particle System
         └──► GPU Rendering (Float32Array views)
```text

## Usage

```typescript
import { DashPensieveBridge } from './dash-pensieve-bridge';

// Initialize bridge
const bridge = new DashPensieveBridge(10000); // max particles

// Create SharedArrayBuffers (must be created on main thread)
const positionBuffer = new SharedArrayBuffer(10000 * 3 * 4); // x,y,z * float32
const colorBuffer = new SharedArrayBuffer(10000 * 3 * 4); // r,g,b * float32
const scaleBuffer = new SharedArrayBuffer(10000 * 4); // scale * float32
const metadataBuffer = new SharedArrayBuffer(10000 * 8 * 4); // metadata

// Initialize buffers
bridge.init_buffers(positionBuffer, colorBuffer, scaleBuffer, metadataBuffer);

// Sync reflections from Dash (JSON string from SQLite query)
const reflections = await dash.execute("SELECT * FROM pensieve_reflections WHERE userId = ?", [userId]);
const reflectionsJson = JSON.stringify(reflections);
const count = bridge.sync_reflections(reflectionsJson);

// Buffers are now updated - Pensieve can read directly
const positionView = new Float32Array(positionBuffer);
const colorView = new Float32Array(colorBuffer);
const scaleView = new Float32Array(scaleBuffer);
```text

## Build

```bash
cd wasm-modules/dash-pensieve-bridge
wasm-pack build --target web --out-dir pkg

Performance

• Zero-copy: No serialization/deserialization overhead
• Shared memory: Both Dash and Pensieve access the same memory
• GPU-friendly: Direct Float32Array views for WebGL rendering
• Thread-safe: SharedArrayBuffer enables cross-thread access (with proper synchronization)

Requirements

• SharedArrayBuffer support (requires Cross-Origin Isolation headers)
• WebAssembly support
• Modern browser (Chrome 92+, Firefox 79+, Safari 15.2+)

Last Updated: 2026-01-31