# Browser Demo

DreamDB includes a fully client-side dataset explorer that runs entirely in the browser. No application server is needed -- the page talks directly to the S3-compatible backend over HTTP.

**Live demo:** [demo.dreamdb.dreamlake.ai](https://demo.dreamdb.dreamlake.ai)

## What the demo does

The browser demo is a single-page application that renders a DreamDB Space URI into an interactive explorer. Given a backend URL and a ref name, it resolves the Manifest, walks every Track, and presents:

- **Dataset explorer** -- a card grid showing every sample in the dataset. Each card displays the image thumbnail (or video player), scalar field values (labels, splits, timestamps), and the sample's time anchor.
- **Semantic search** -- type a natural-language query and the demo encodes it with CLIP (ViT-B/32, running client-side via `transformers.js`) and performs a vector search against the dataset's embedding index. Results are ranked by cosine similarity.
- **Time-travel** -- the history panel lists every Manifest in the ref's parent chain. Click any entry to re-render the entire view at that point in time. This is the same immutable Object graph that powers the Python SDK's `Dataset.open_at()`.
- **Video playback** -- video fields render inline with HLS streaming support for chunked items.
- **Point cloud viewer** -- 3D LiDAR and scene-update tracks render in an interactive Three.js viewport with orbit controls.

## Connecting your own data

### Point at a local MinIO instance

If you followed the [Quick Start](/tutorial.md) and have MinIO running on `localhost:9000`, open the demo and enter:

- **Backend URL:** `http://localhost:9000/tutorial`
- **Ref name:** `multimodal`

The demo loads the Manifest, resolves all Tracks, and renders the samples.

### Add your own S3 bucket

To browse a dataset on AWS S3 or another hosted backend:

1. Ensure the bucket allows public read access (or configure CORS to permit browser requests from the demo origin).
2. Enter the full backend URL, e.g. `https://s3.us-east-1.amazonaws.com/my-bucket`.
3. Enter the ref name of the dataset you want to browse.

The demo stores your backend list in `localStorage` so you do not need to re-enter it on each visit.

### CORS configuration

For cross-origin access from the browser, the S3 bucket must return appropriate CORS headers. A minimal MinIO policy:

```bash
docker exec dreamdb-minio mc anonymous set public local/my-bucket
```

For AWS S3, add a CORS configuration to the bucket:

```json
{
  "CORSRules": [
    {
      "AllowedOrigins": ["*"],
      "AllowedMethods": ["GET", "HEAD"],
      "AllowedHeaders": ["*"],
      "MaxAgeSeconds": 3600
    }
  ]
}
```

## Features in detail

### Dataset structure panel

The top of the page shows the dataset's structural metadata: Manifest hash, timeline ID, writer identity, and a badge for each Track (image, video, embedding, scalar). Badges show the item count per track and distinguish fragment, spatial, and scalar tracks by color.

### Semantic search

The search bar loads the CLIP text encoder (ViT-B/32) on first use via [transformers.js](https://huggingface.co/docs/transformers.js). The text query is encoded into a 512-dimensional vector and matched against the dataset's embedding index using DreamDB's IVF + RaBitQ spatial search -- all running in the browser, no server round-trip.

Search results update the grid in ranked order. Each card shows its cosine similarity score.

### Time-travel history

Click the history button to see every Manifest in the dataset's parent DAG, ordered newest to oldest. Each entry shows:

- Manifest hash (base32)
- Writer-asserted timestamp
- Track count and modality summary
- Parent count (0 for genesis, 1 for normal appends, 2+ for merges)

Click any history entry to re-render the entire explorer at that prior state. Because every Object is content-addressed and immutable, historical views are as fast and reliable as the current one.

### Time-range queries

Select a time window to filter samples to a specific range of anchors. The demo uses `DreamDBSpace.itemsInRange()` to restrict the view without re-fetching every Track.

## Running the demo locally

The demo is a static HTML page with no build step:

```bash
cd demo
python -m http.server 8080
```

Open `http://localhost:8080/browse.html` in a modern browser. The page loads `dreamdb.js` (the DreamDB browser SDK) and `viz.js` (the Three.js-based point cloud renderer) as plain script tags.

## Architecture

The browser SDK (`dreamdb.js`) implements the same protocol primitives as the Rust and Python SDKs:

- **Multihash + base32** addressing for content-addressed Objects
- **CBOR decoding** for Manifests, Tracks, and Buckets
- **Space URI parsing** to resolve refs and manifests from any S3 endpoint
- **Concurrent fetch** with bounded parallelism (32 in-flight requests) for Track and Bucket resolution

No WebAssembly or native modules are involved. The entire SDK is a single JavaScript file that runs in any browser with `fetch` and `DataView` support.