docs: add devtools section to api.md and getting-started; update ROADMAP

Author: a-saed

ROADMAP.md

@@ -20,6 +20,7 @@ Today datum uses last-write-wins based on `updated_at`. For collaborative editin
 
 ## Recently shipped
 
+- **DevTools (v0.8.0)** — `datum-sync/devtools` adds a floating browser panel with a SQL REPL (full PostGIS), schema inspector, and live sync status. Activated by `initDatumDevtools(db)`. Toggle with `Ctrl+Shift+D`. Zero production bundle impact via dynamic import. Try it at the [live demo](https://a-saed.github.io/datum/demo/).
 - **Typed column support (v0.7.0)** — datum auto-introspects the server table at startup and mirrors the exact column structure in PGlite. Any columns beyond the 4 required ones (`id`, `geom`, `updated_at`, `properties`) are synced automatically and queryable with normal SQL on both sides — no extra configuration.
 - **Per-user authentication (v0.6.0)** — JWT auth (HS256/RS256/ES256). Token in `subscribe` message, all claims forwarded as `datum.<key>` Postgres session variables for RLS. Auto token refresh before expiry. Startup warning when connected as superuser. Fully opt-in.
 - **Security and correctness hardening (0.5.0)** — Ack-based write sync (server acks writes before client marks synced; retries on reconnect). WS per-connection read limits, read deadlines, ping/pong keepalive. Write batch capped at 500. Rate limiter uses real client IP (X-Forwarded-For aware). Delta broadcast uses full geometry bbox (not just first vertex) for correct routing of polygons and lines. Graceful shutdown on SIGTERM. Outbox ordered by insertion seq not feature timestamp.

docs/api.md

@@ -228,6 +228,70 @@ function FeatureList() {
 
 ---
 
+## DevTools (`datum-sync/devtools`)
+
+A floating browser panel for inspecting the local PGlite database, schema, and sync state while building. Zero production bundle impact — loaded only when you import it.
+
+```ts
+import { initDatumDevtools } from 'datum-sync/devtools'
+```
+
+### `initDatumDevtools(client)`
+
+Injects the devtools panel into the page. Call once after `DatumClient.connect()`.
+
+```ts
+const db = await DatumClient.connect({ serverUrl, bbox })
+
+// Dev only — tree-shaken out of production builds when using dynamic import
+if (import.meta.env.DEV) {
+  const { initDatumDevtools } = await import('datum-sync/devtools')
+  initDatumDevtools(db)
+}
+```
+
+For multiple tables, pass an array — a dropdown appears in the toolbar to switch between clients:
+
+```ts
+initDatumDevtools([featuresDb, waypointsDb])
+```
+
+Calling `initDatumDevtools` more than once is a no-op (idempotent).
+
+**Toggle:** `Ctrl+Shift+D` (Windows/Linux) or `Cmd+Shift+D` (Mac). The panel remembers its open/closed state and height across page reloads via `localStorage`.
+
+### Tabs
+
+| Tab | What it shows |
+|---|---|
+| **Query** | SQL REPL against local PGlite. Full PostGIS available. `Cmd+Enter` to run. |
+| **Schema** | Every column from the server's schema message — name, type, role badge, nullable. Schema hash and "mirrored from server ✓" confirmation. |
+| **Status** | Connection state, pending write count, schema hash, schema version. When a schema wipe occurs, shows a diff of added/removed columns. |
+
+### `onSchemaChange` callback
+
+Called whenever the local DB is wiped and recreated (schema changed or first visit). Available in `DatumConfig` and as a post-connect subscription:
+
+```ts
+// In config (set at connect time):
+const db = await DatumClient.connect({
+  serverUrl,
+  bbox,
+  onSchemaChange: ({ prev, next }) => {
+    console.log('Schema changed — columns now:', next.map(c => c.name))
+  },
+})
+
+// Post-connect subscription (returns unsubscribe function):
+const unsub = db.onSchemaChange(({ prev, next }) => {
+  console.log('added columns:', next.filter(c => !prev?.find(p => p.name === c.name)))
+})
+```
+
+`prev` is `null` on first visit (no previous schema). `next` is the full column list after the wipe.
+
+---
+
 ## datum-server (Go binary)
 
 ### Config file

docs/getting-started.md

@@ -91,9 +91,24 @@ import { useDatum } from 'datum-sync/react'
 const { rows } = useDatum(db, `SELECT * FROM features`)
 ```
 
+## DevTools
+
+Add the datum devtools panel to inspect your local PGlite database while building:
+
+```ts
+const db = await DatumClient.connect({ serverUrl, bbox })
+
+if (import.meta.env.DEV) {
+  const { initDatumDevtools } = await import('datum-sync/devtools')
+  initDatumDevtools(db)
+}
+```
+
+Press `Ctrl+Shift+D` to toggle the panel. Three tabs: **Query** (SQL REPL), **Schema** (column inspector), **Status** (sync state). No extra dependencies — included in `datum-sync`.
+
 ## Next steps
 
 - [How It Works](/how-it-works) — understand the local-first model, bbox subscriptions, and sync cycle
-- [API Reference](/api) — full TypeScript client, React hooks, and server documentation
+- [API Reference](/api) — full TypeScript client, React hooks, devtools, and server documentation
 - [Authentication](/auth) — add per-user JWT auth and Postgres Row Level Security
 - [Self-Hosting](/self-hosting) — deploy to production (free-tier guide included)