@prabhask5/stellar-engine 1.2.0 → 1.2.2

package/README.md

@@ -1,539 +1,607 @@
 # @prabhask5/stellar-engine [![npm version](https://img.shields.io/npm/v/@prabhask5/stellar-engine.svg?style=flat)](https://www.npmjs.com/package/@prabhask5/stellar-engine) [![Made with Supabase](https://supabase.com/badge-made-with-supabase-dark.svg)](https://supabase.com)
 
-A local-first, offline-capable sync engine for **SvelteKit + Supabase + Dexie** applications. All reads come from IndexedDB, all writes land locally first, and a background sync loop ships changes to Supabase -- so your app stays fast and functional regardless of network state.
+A plug-and-play, offline-first sync engine for **Supabase + Dexie.js** applications. All reads come from IndexedDB, all writes land locally first, and a background sync loop ships changes to Supabase -- so your app stays fast and functional regardless of network state. Optional **SvelteKit** integrations are included for teams building with Svelte 5, but the core engine works with any framework or vanilla JS.
 
 ## Documentation
 
-- [API Reference](./API_REFERENCE.md) -- full signatures, parameters, and usage examples for every public export
 - [Architecture](./ARCHITECTURE.md) -- internal design, data flow, and module responsibilities
-- [Framework Integration](./FRAMEWORKS.md) -- SvelteKit-specific patterns and conventions
+- [API Reference](./API_REFERENCE.md) -- full signatures, parameters, and usage examples for every public export
+- [Frameworks](./FRAMEWORKS.md) -- more reading on frameworks used in stellar-engine
 
 ## Features
 
-- **Intent-based sync operations** -- operations preserve intent (`increment`, `set`, `create`, `delete`) instead of just final state, enabling smarter coalescing and conflict handling.
-- **Three-tier conflict resolution** -- field-level diffing, numeric merge fields, and configurable exclusion lists let you resolve conflicts precisely rather than with blanket last-write-wins.
-- **Offline authentication** -- credential caching and offline session tokens let users sign in and work without connectivity; sessions reconcile automatically on reconnect.
-- **Single-user auth mode** -- for personal apps, use a simplified PIN code or password gate backed by real Supabase email/password auth. The user provides an email during setup; the PIN is padded to meet Supabase's minimum password length and verified server-side. Setup, unlock, lock, and gate change are all handled by the engine with full offline support.
-- **Realtime subscriptions** -- Supabase Realtime channels push remote changes into local state instantly, with duplicate-delivery guards to prevent re-processing.
-- **Operation coalescing** -- batches of rapid local writes (e.g., 50 individual increments) are compressed into a single outbound operation, reducing sync traffic dramatically.
-- **Tombstone management** -- soft deletes are propagated cleanly, and stale tombstones are garbage-collected after a configurable retention period.
-- **Egress optimization** -- column-level select lists and ownership filters ensure only the data your client needs is fetched from Supabase.
+- **Schema-driven configuration** -- declare tables once in a simple object; the engine auto-generates Dexie stores, database versioning, TypeScript interfaces, and Supabase SQL
+- **Intent-based sync operations** -- operations preserve intent (`increment`, `set`, `create`, `delete`) instead of final state, enabling smarter coalescing and conflict handling
+- **6-step operation coalescing** -- 50 rapid writes are compressed into 1 outbound operation, dramatically reducing sync traffic
+- **Three-tier conflict resolution** -- field-level auto-merge for non-overlapping changes, different-field merge, and same-field resolution (`local_pending` > `delete_wins` > `last_write_wins` with device ID tiebreaker)
+- **Offline authentication** -- SHA-256 credential caching and offline session tokens let users sign in and work without connectivity; sessions reconcile automatically on reconnect
+- **Single-user PIN/password auth** -- simplified gate backed by real Supabase email/password auth; PIN is padded to meet minimum length and verified server-side
+- **Device verification** -- email OTP for untrusted devices with configurable trust duration
+- **Realtime subscriptions** -- Supabase Realtime WebSocket push with echo suppression and deduplication against polling
+- **Tombstone management** -- soft deletes with configurable garbage collection
+- **Egress optimization** -- column-level selects, operation coalescing, push-only mode when realtime is healthy, cursor-based pulls
+- **CRDT collaborative editing** -- optional Yjs-based subsystem for real-time multi-user editing via Supabase Broadcast
+- **Demo mode** -- sandboxed database, zero Supabase connections, mock auth for instant onboarding experiences
+- **Reactive stores** -- Svelte-compatible stores for sync status, auth state, network state, and remote changes
+- **Store factories** -- `createCollectionStore` and `createDetailStore` for boilerplate-free reactive data layers
+- **Svelte actions** -- `remoteChangeAnimation`, `trackEditing`, `triggerLocalAnimation` for declarative UI behavior
+- **SQL generation** -- auto-generate `CREATE TABLE` statements, RLS policies, and migrations from your schema config
+- **TypeScript generation** -- auto-generate interfaces from schema
+- **Migration generation** -- auto-generate `ALTER TABLE` rename and column rename SQL from `renamedFrom` / `renamedColumns` hints
+- **Diagnostics** -- comprehensive runtime diagnostics covering sync, queue, realtime, conflicts, egress, and network
+- **Debug utilities** -- opt-in debug logging and `window` debug utilities for browser console inspection
+- **SvelteKit integration** (optional) -- layout helpers, server handlers, email confirmation, service worker lifecycle, and auth hydration
+- **PWA scaffolding CLI** -- `stellar-engine install pwa` generates a complete SvelteKit PWA project (34+ files)
+
+### Use cases
+
+- Productivity and task management apps
+- Notion-like block editors (with CRDT collaborative editing)
+- Personal finance trackers (numeric merge across devices)
+- File and asset management UIs (fractional ordering for drag-and-drop)
+- Habit trackers and daily planners
+- Knowledge bases and note-taking apps
+- Any app needing offline-first multi-device sync
 
 ## Quick start
 
-Install from npm:
-
-```bash
-npm install @prabhask5/stellar-engine
-```
+```ts
+// ─── Install ───────────────────────────────────────────────────────
+// npm install @prabhask5/stellar-engine
 
-Initialize the engine at app startup (e.g., in a SvelteKit root `+layout.ts`):
+// ─── 1. Initialize the engine ──────────────────────────────────────
+// Call once at app startup (e.g., root layout, main entry point).
+// Schema-driven: declare tables once, engine handles everything else.
 
-```ts
-import { initEngine, startSyncEngine, supabase } from '@prabhask5/stellar-engine';
+import { initEngine, startSyncEngine, getDb, resetDatabase } from '@prabhask5/stellar-engine';
 import { initConfig } from '@prabhask5/stellar-engine/config';
 import { resolveAuthState } from '@prabhask5/stellar-engine/auth';
 
 initEngine({
   prefix: 'myapp',
-  supabase,
-  tables: [
-    {
-      supabaseName: 'projects',
-      columns: 'id, name, created_at, updated_at, is_deleted, user_id',
+
+  // Schema-driven: declare tables once, engine handles the rest.
+  // System indexes (id, user_id, created_at, updated_at, deleted, _version)
+  // are auto-appended to every table. Database name auto-derived as `${prefix}DB`.
+  schema: {
+    projects: 'order',                              // String shorthand = indexes only
+    tasks: 'project_id, order',                     // Comma-separated Dexie indexes
+    focus_settings: { singleton: true },             // Object form for full control
+    goals: {
+      indexes: 'goal_list_id, order',
+      numericMergeFields: ['current_value'],         // Additive merge on conflicts
+      excludeFromConflict: ['device_id'],            // Skip these in conflict diffing
     },
-    // ...more tables
-  ],
-  database: {
-    name: 'MyAppDB',
-    versions: [
-      {
-        version: 1,
-        stores: {
-          projects: 'id, user_id, updated_at',
-          tasks: 'id, project_id, user_id, updated_at',
-        }
-      }
-    ]
   },
+
+  // Auth: flat format with sensible defaults (all fields optional).
+  // No nested `singleUser` key needed -- engine normalizes internally.
   auth: {
-    enableOfflineAuth: true,
+    gateType: 'code',                               // 'code' | 'password' (default: 'code')
+    codeLength: 6,                                   // 4 | 6 (default: 6)
+    emailConfirmation: true,                         // default: true
+    deviceVerification: true,                        // default: true
+    profileExtractor: (meta) => ({ firstName: meta.first_name }),
+    profileToMetadata: (p) => ({ first_name: p.firstName }),
   },
-});
 
-await initConfig();
-const auth = await resolveAuthState();
-if (auth.authMode !== 'none') await startSyncEngine();
-```
-
-### Single-user mode
-
-For personal apps with a PIN code gate backed by real Supabase email/password auth:
-
-```ts
-import { initEngine, startSyncEngine, supabase } from '@prabhask5/stellar-engine';
-import { initConfig } from '@prabhask5/stellar-engine/config';
-import { resolveAuthState } from '@prabhask5/stellar-engine/auth';
+  // Optional CRDT collaborative editing
+  crdt: true,  // or { persistIntervalMs: 60000, maxOfflineDocuments: 50 }
 
-initEngine({
-  prefix: 'myapp',
-  supabase,
-  tables: [/* ... */],
-  database: {/* ... */},
-  auth: {
-    singleUser: { gateType: 'code', codeLength: 4 },
-    enableOfflineAuth: true,
-    // emailConfirmation: { enabled: true },       // require email confirmation on setup
-    // deviceVerification: { enabled: true },       // require OTP verification on new devices
+  // Optional demo mode
+  demo: {
+    seedData: async (db) => {
+      await db.table('projects').bulkPut([
+        { id: 'demo-1', name: 'Sample Project', order: 1 },
+      ]);
+    },
+    mockProfile: { email: 'demo@test.com', firstName: 'Demo', lastName: 'User' },
   },
+
+  // Tuning (all optional with defaults)
+  syncDebounceMs: 2000,        // Default: 2000
+  syncIntervalMs: 900000,      // Default: 900000 (15 min)
+  tombstoneMaxAgeDays: 7,      // Default: 7
 });
 
+// ─── 2. Resolve auth and start the engine ──────────────────────────
+// The engine fetches runtime config (Supabase URL + anon key) from
+// your /api/config endpoint -- no need to pass a supabase client.
+
 await initConfig();
 const auth = await resolveAuthState();
 
 if (!auth.singleUserSetUp) {
-  // Show setup screen → call setupSingleUser(code, profile, email)
-  // Returns { error, confirmationRequired }
-  // If confirmationRequired, prompt user to check email then call completeSingleUserSetup()
+  // First-time setup flow
+  // -> call setupSingleUser(code, profile, email) from your UI
 } else if (auth.authMode === 'none') {
-  // Show unlock screen → call unlockSingleUser(code)
-  // Returns { error, deviceVerificationRequired?, maskedEmail? }
-  // If deviceVerificationRequired, prompt for OTP then call completeDeviceVerification(tokenHash?)
+  // Locked -- show unlock screen
+  // -> call unlockSingleUser(code) from your UI
 } else {
+  // Authenticated -- start syncing
   await startSyncEngine();
 }
-```
 
-## Install PWA Command
+// ─── 3. CRUD operations ────────────────────────────────────────────
 
-Scaffold a complete offline-first PWA project with an interactive walkthrough:
+import {
+  engineCreate,
+  engineUpdate,
+  engineDelete,
+  engineIncrement,
+  engineBatchWrite,
+  queryAll,
+  queryOne,
+  engineGetOrCreate,
+} from '@prabhask5/stellar-engine/data';
+import { generateId, now } from '@prabhask5/stellar-engine/utils';
+
+// Create
+const projectId = generateId();
+await engineCreate('projects', {
+  id: projectId,
+  name: 'New Project',
+  order: 1,
+  created_at: now(),
+  updated_at: now(),
+  deleted: false,
+  user_id: 'current-user-id',
+});
 
-```bash
-npx @prabhask5/stellar-engine install pwa
-```
+// Update (only changed fields are synced)
+await engineUpdate('tasks', taskId, {
+  title: 'Updated title',
+  updated_at: now(),
+});
 
-The wizard guides you through each option (app name, short name, prefix, description), validates input inline, shows a confirmation summary, then scaffolds with animated progress.
+// Delete (soft delete -- tombstone managed by engine)
+await engineDelete('tasks', taskId);
 
-### What it generates
+// Increment (intent-preserved -- concurrent increments merge correctly)
+await engineIncrement('goals', goalId, 'current_value', 1);
 
-The command creates a full SvelteKit 2 + Svelte 5 project with:
+// Query all rows from local IndexedDB
+const projects = await queryAll('projects');
 
-**Configuration files (8):** `vite.config.ts`, `tsconfig.json`, `svelte.config.js`, `eslint.config.js`, `.prettierrc`, `.prettierignore`, `knip.json`, `.gitignore`
+// Query a single row
+const project = await queryOne('projects', projectId);
 
-**Documentation (3):** `README.md`, `ARCHITECTURE.md`, `FRAMEWORKS.md`
+// Get or create (atomic upsert)
+const { record, created } = await engineGetOrCreate('focus_settings', settingsId, {
+  id: settingsId,
+  theme: 'dark',
+  created_at: now(),
+  updated_at: now(),
+  deleted: false,
+  user_id: 'current-user-id',
+});
 
-**Static assets (13):** `manifest.json`, `offline.html`, placeholder SVG icons (app, dark, maskable, favicon, monochrome, splash, apple-touch), email template placeholders (signup, change-email, device-verification)
+// Batch writes (multiple operations in one sync push)
+await engineBatchWrite([
+  { type: 'create', table: 'tasks', data: { id: generateId(), title: 'Task 1', project_id: projectId, order: 1, created_at: now(), updated_at: now(), deleted: false, user_id: 'uid' } },
+  { type: 'create', table: 'tasks', data: { id: generateId(), title: 'Task 2', project_id: projectId, order: 2, created_at: now(), updated_at: now(), deleted: false, user_id: 'uid' } },
+  { type: 'update', table: 'projects', id: projectId, data: { updated_at: now() } },
+]);
 
-**Database (1):** `supabase-schema.sql` with helper functions, example table pattern, and `trusted_devices` table
+// ─── 4. Reactive store factories ───────────────────────────────────
 
-**Source files (2):** `src/app.html` (PWA-ready with iOS meta tags, landscape blocker, zoom prevention, SW registration), `src/app.d.ts`
+import { createCollectionStore, createDetailStore } from '@prabhask5/stellar-engine/stores';
 
-**Route files (16):**
-| File | What stellar-engine manages | What you customize (TODO) |
-|------|---------------------------|--------------------------|
-| `src/routes/+layout.ts` | Auth resolution, config init, sync engine startup via `resolveAuthState()`, `initConfig()`, `startSyncEngine()` | `initEngine()` config with your database schema |
-| `src/routes/+layout.svelte` | Auth state hydration via `hydrateAuthState()` | App shell (navbar, tab bar, overlays) |
-| `src/routes/+page.svelte` | Imports `resolveFirstName`, `onSyncComplete`, `authState`; derives `firstName` reactively | Home page UI |
-| `src/routes/+error.svelte` | — | Error page UI |
-| `src/routes/setup/+page.ts` | Config check, session validation via `getConfig()`, `getValidSession()` | — (fully managed) |
-| `src/routes/setup/+page.svelte` | Imports `setConfig`, `isOnline`, `pollForNewServiceWorker` | Setup wizard UI |
-| `src/routes/policy/+page.svelte` | — | Privacy policy content |
-| `src/routes/login/+page.svelte` | All auth functions: `setupSingleUser`, `unlockSingleUser`, `getSingleUserInfo`, `completeSingleUserSetup`, `completeDeviceVerification`, `pollDeviceVerification`, `fetchRemoteGateConfig`, `linkSingleUserDevice`, `sendDeviceVerification` | Login page UI |
-| `src/routes/confirm/+page.svelte` | Email confirmation via `handleEmailConfirmation()`, `broadcastAuthConfirmed()` | Confirmation page UI |
-| `src/routes/api/config/+server.ts` | Fully managed: `getServerConfig()` | — |
-| `src/routes/api/setup/deploy/+server.ts` | Fully managed: `deployToVercel()` | — |
-| `src/routes/api/setup/validate/+server.ts` | Fully managed: `createValidateHandler()` | — |
-| `src/routes/[...catchall]/+page.ts` | Redirect to `/` | — |
-| `src/routes/(protected)/+layout.ts` | Auth guard via `resolveAuthState()` with login redirect | — (fully managed) |
-| `src/routes/(protected)/+layout.svelte` | — | Protected area chrome |
-| `src/routes/(protected)/profile/+page.svelte` | All profile functions: `changeSingleUserGate`, `updateSingleUserProfile`, `getSingleUserInfo`, `changeSingleUserEmail`, `completeSingleUserEmailChange`, `resetDatabase`, `getTrustedDevices`, `removeTrustedDevice`, `getCurrentDeviceId`, `isDebugMode`, `setDebugMode` | Profile page UI |
+// Collection store -- live-updating list from IndexedDB
+const projectsStore = createCollectionStore('projects', {
+  filter: (p) => !p.deleted,
+  sort: (a, b) => a.order - b.order,
+});
+// Subscribe: projectsStore.subscribe(items => { ... })
 
-**Library (1):** `src/lib/types.ts` with re-exports from stellar-engine + app-specific type stubs
+// Detail store -- single record by ID
+const projectDetail = createDetailStore('projects', projectId);
+// Subscribe: projectDetail.subscribe(record => { ... })
 
-**Git hooks (1):** `.husky/pre-commit` with lint + format + validate
+// ─── 5. Reactive stores ────────────────────────────────────────────
 
-### Interactive Prompts
+import {
+  syncStatusStore,
+  authState,
+  isOnline,
+  remoteChangesStore,
+  onSyncComplete,
+} from '@prabhask5/stellar-engine/stores';
+
+// $syncStatusStore -- current SyncStatus, last sync time, errors
+// $authState       -- { mode, session, offlineProfile, isLoading, authKickedMessage }
+// $isOnline        -- reactive boolean reflecting network state
+// remoteChangesStore -- tracks entities recently changed by remote peers
+
+// Listen for sync completions
+onSyncComplete(() => {
+  console.log('Sync cycle finished');
+});
 
-| Prompt | Required | Description |
-|--------|----------|-------------|
-| App Name | Yes | Full app name (e.g., "Stellar Planner") |
-| Short Name | Yes | Short name for PWA home screen (under 12 chars) |
-| Prefix | Yes | Lowercase key for localStorage, caches, SW (auto-suggested from name) |
-| Description | No | App description (default: "A self-hosted offline-first PWA") |
+// ─── 6. Svelte actions ─────────────────────────────────────────────
 
-## Subpath exports
+import { remoteChangeAnimation, trackEditing } from '@prabhask5/stellar-engine/actions';
 
-Import only what you need via subpath exports:
+// use:remoteChangeAnimation={{ table: 'tasks', id: task.id }}
+// Animates elements when remote changes arrive for that entity.
 
-| Subpath | Contents |
-|---|---|
-| `@prabhask5/stellar-engine` | `initEngine`, `startSyncEngine`, `runFullSync`, `supabase`, `getDb`, `validateSupabaseCredentials`, `validateSchema` |
-| `@prabhask5/stellar-engine/data` | All engine CRUD + query operations (`engineCreate`, `engineUpdate`, etc.) |
-| `@prabhask5/stellar-engine/auth` | All auth functions (`resolveAuthState`, `signOut`, `setupSingleUser`, `unlockSingleUser`, `lockSingleUser`, `completeSingleUserSetup`, `completeDeviceVerification`, `changeSingleUserEmail`, `completeSingleUserEmailChange`, `padPin`, etc.) |
-| `@prabhask5/stellar-engine/stores` | Reactive stores + event subscriptions (`syncStatusStore`, `authState`, `onSyncComplete`, etc.) |
-| `@prabhask5/stellar-engine/types` | All type exports (`Session`, `SyncEngineConfig`, `BatchOperation`, `SingleUserConfig`, etc.) |
-| `@prabhask5/stellar-engine/utils` | Utility functions (`generateId`, `now`, `calculateNewOrder`, `snakeToCamel`, `debug`, etc.) |
-| `@prabhask5/stellar-engine/actions` | Svelte `use:` actions (`remoteChangeAnimation`, `trackEditing`, `triggerLocalAnimation`, `truncateTooltip`) |
-| `@prabhask5/stellar-engine/kit` | SvelteKit route helpers, server APIs, load functions, confirmation, auth hydration |
-| `@prabhask5/stellar-engine/components/SyncStatus` | Sync status indicator Svelte component |
-| `@prabhask5/stellar-engine/components/DeferredChangesBanner` | Cross-device conflict banner Svelte component |
-| `@prabhask5/stellar-engine/config` | Runtime config (`initConfig`, `getConfig`, `setConfig`, `getDexieTableFor`) |
-
-The root export (`@prabhask5/stellar-engine`) re-exports everything for backward compatibility.
-
-## Requirements
-
-**Supabase**
-
-Your Supabase project needs tables matching the `supabaseName` entries in your config. The corresponding Dexie (IndexedDB) table name is automatically derived from `supabaseName` using `snakeToCamel()` conversion (e.g., `goal_lists` becomes `goalLists`). Each table should have at minimum:
-- `id` (uuid primary key)
-- `updated_at` (timestamptz) -- used as the sync cursor
-- `is_deleted` (boolean, default false) -- for soft-delete / tombstone support
-- An ownership column (e.g., `user_id`) if you use `ownershipFilter`
-
-Row-Level Security policies should scope reads and writes to the authenticated user.
-
-**Single-user mode additional requirements:**
-
-Single-user mode uses real Supabase email/password auth where the PIN is padded to meet Supabase's minimum password length. The user provides an email during setup, and the PIN is verified server-side.
-
-If `deviceVerification` is enabled in the auth config, you need a `trusted_devices` table:
-
-```sql
-CREATE TABLE trusted_devices (
-  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-  user_id uuid REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL,
-  device_id text NOT NULL,
-  device_label text,
-  trusted_at timestamptz DEFAULT now() NOT NULL,
-  last_used_at timestamptz DEFAULT now() NOT NULL,
-  UNIQUE(user_id, device_id)
-);
-ALTER TABLE trusted_devices ENABLE ROW LEVEL SECURITY;
-CREATE POLICY "Users manage own devices" ON trusted_devices FOR ALL
-  USING (auth.uid() = user_id) WITH CHECK (auth.uid() = user_id);
-```
+// use:trackEditing={{ table: 'tasks', id: task.id }}
+// Signals the engine a field is being actively edited (suppresses incoming overwrites).
 
-If `emailConfirmation` is enabled, Supabase email templates must be configured. See [EMAIL_TEMPLATES.md](./EMAIL_TEMPLATES.md) for the full HTML templates for signup confirmation, email change confirmation, and device verification emails.
+// ─── 7. CRDT collaborative editing ────────────────────────────────
 
-**Schema validation:** The engine automatically validates that all configured tables (and `trusted_devices` when `deviceVerification.enabled`) exist in Supabase on the first sync. Missing tables are reported via `syncStatusStore` and the debug console.
+import {
+  openDocument,
+  closeDocument,
+  createSharedText,
+  createBlockDocument,
+  updateCursor,
+  getCollaborators,
+  onCollaboratorsChange,
+} from '@prabhask5/stellar-engine/crdt';
 
-**Dexie (IndexedDB)**
+// Open a collaborative document (uses Supabase Broadcast -- zero DB writes per keystroke)
+const provider = await openDocument('doc-1', 'page-1', {
+  offlineEnabled: true,
+  initialPresence: { name: 'Alice' },
+});
 
-When you provide a `database` config to `initEngine`, the engine creates and manages the Dexie instance for you. System tables (`syncQueue`, `conflictHistory`, `offlineCredentials`, `offlineSession`, `singleUserConfig`) are automatically merged into every schema version -- you only declare your application tables. Note that the store keys use the **camelCase** Dexie table names (auto-derived from `supabaseName` via `snakeToCamel()`):
+// Use with any Yjs-compatible editor (Tiptap, BlockNote, etc.)
+const { content, meta } = createBlockDocument(provider.doc);
+meta.set('title', 'My Page');
 
-```ts
-database: {
-  name: 'MyAppDB',
-  versions: [
-    {
-      version: 1,
-      stores: {
-        projects: 'id, user_id, updated_at',
-        tasks: 'id, project_id, user_id, updated_at',
-      }
-    }
-  ]
+// Shared text for simpler use cases
+const text = createSharedText(provider.doc);
+
+// Track collaborator cursors and presence
+const unsub = onCollaboratorsChange('doc-1', (collaborators) => {
+  // Update avatar list, cursor positions, etc.
+});
+
+await closeDocument('doc-1');
+
+// ─── 8. Demo mode ──────────────────────────────────────────────────
+
+import { setDemoMode, isDemoMode } from '@prabhask5/stellar-engine';
+
+// Check if demo mode is active
+if (isDemoMode()) {
+  // In demo mode:
+  // - Uses '${prefix}DB_demo' IndexedDB (real DB never opened)
+  // - Zero Supabase network requests
+  // - authMode === 'demo', protected routes work with mock data
+  // - seedData callback runs on each page load
 }
-```
 
-Alternatively, you can provide a pre-created Dexie instance via the `db` config option for full control.
+// Toggle demo mode from your UI (requires full page reload)
+setDemoMode(true);
+window.location.href = '/';
+
+// ─── 9. SQL and TypeScript generation ──────────────────────────────
+
+import { generateSupabaseSQL, generateTypeScript } from '@prabhask5/stellar-engine/utils';
+import { getEngineConfig } from '@prabhask5/stellar-engine';
+
+const config = getEngineConfig();
+
+// Auto-generate Supabase SQL (CREATE TABLE + RLS policies) from schema
+const sql = generateSupabaseSQL(config.schema!);
+
+// Auto-generate TypeScript interfaces from schema
+const ts = generateTypeScript(config.schema!);
+
+// ─── 10. Diagnostics and debug ─────────────────────────────────────
+
+import { setDebugMode, isDebugMode } from '@prabhask5/stellar-engine/utils';
+import { getDiagnostics } from '@prabhask5/stellar-engine';
 
-## Architecture
+setDebugMode(true);
 
+// Comprehensive runtime diagnostics
+const diagnostics = await getDiagnostics();
+// diagnostics.sync     -- sync cycle statistics and recent cycle details
+// diagnostics.queue    -- pending operation queue state
+// diagnostics.realtime -- realtime connection state and health
+// diagnostics.conflict -- conflict resolution history and stats
+// diagnostics.egress   -- data transfer from Supabase (bytes, per-table breakdown)
+// diagnostics.network  -- network state and connectivity info
+
+// When debug mode is enabled, utilities are exposed on `window`:
+// window.__myappSyncStats(), window.__myappEgress(), window.__myappTombstones()
+// window.__myappSync.forceFullSync()
 ```
-+---------------------+
-|   Application UI    |
-+---------------------+
-         |
-         v
-+---------------------+       +-------------------+
-|    Repositories     | ----> |    Dexie (IDB)    |
-| (read/write local)  |       |  - app tables     |
-+---------------------+       |  - syncQueue      |
-         |                    |  - conflictHistory |
-         | queueSyncOperation +-------------------+
-         v                              ^
-+---------------------+                |
-|    Sync Engine      | ---------------+
-|  - coalesce ops     |    hydrate / reconcile
-|  - push to remote   |
-|  - pull from remote  |
-|  - resolve conflicts |
-+---------------------+
-         |
-         v
-+---------------------+       +---------------------+
-|   Supabase REST     |       | Supabase Realtime   |
-|   (push / pull)     |       | (live subscriptions)|
-+---------------------+       +---------------------+
+
+## Commands
+
+### Install PWA
+
+Scaffold a complete offline-first SvelteKit PWA project with an interactive walkthrough:
+
+```bash
+npx @prabhask5/stellar-engine install pwa
 ```
 
-1. **Repositories** read from and write to Dexie, then enqueue a `SyncOperationItem` describing the intent of the change.
-2. **The engine** debounces outbound operations, coalesces them, and pushes to Supabase via REST. On pull, it fetches rows newer than the local sync cursor and reconciles them with any pending local operations.
-3. **Realtime** channels deliver server-side changes immediately, skipping the next poll cycle when the subscription is healthy.
+The wizard prompts for:
+
+| Prompt | Required | Description |
+|--------|----------|-------------|
+| App Name | Yes | Full app name (e.g., "Stellar Planner") |
+| Short Name | Yes | Short name for PWA home screen (under 12 chars) |
+| Prefix | Yes | Lowercase key for localStorage, caches, SW (auto-suggested from name) |
+| Description | No | App description (default: "A self-hosted offline-first PWA") |
+
+Generates **34+ files** for a production-ready SvelteKit 2 + Svelte 5 project:
+
+- **Config files (8):** `vite.config.ts`, `tsconfig.json`, `svelte.config.js`, `eslint.config.js`, `.prettierrc`, `.prettierignore`, `knip.json`, `.gitignore`
+- **Documentation (3):** `README.md`, `ARCHITECTURE.md`, `FRAMEWORKS.md`
+- **Static assets (13):** `manifest.json`, `offline.html`, placeholder SVG icons, email template placeholders
+- **Database (1):** `supabase-schema.sql` with helper functions, example tables, and `trusted_devices` table
+- **Source files (2):** `src/app.html` (PWA-ready with iOS meta tags, SW registration), `src/app.d.ts`
+- **Route files (16):** Root layout, login, setup, profile, protected area, API endpoints, catch-all redirect
+- **Library (1):** `src/lib/types.ts` with re-exports and app-specific type stubs
+- **Git hooks (1):** `.husky/pre-commit` with lint + format + validate
 
 ## API overview
 
-### Configuration
+### Engine Configuration and Lifecycle
 
 | Export | Description |
 |---|---|
-| `initEngine(config)` | Initialize the engine with table definitions, Supabase client, and Dexie instance. |
-| `getEngineConfig()` | Retrieve the current config (throws if not initialized). |
-| `SyncEngineConfig` / `TableConfig` | TypeScript interfaces for the config objects. `TableConfig` uses `supabaseName` only; Dexie table names are auto-derived. |
+| `initEngine(config)` | Initialize the engine with schema, auth, and optional CRDT/demo config |
+| `startSyncEngine()` | Start the sync loop, realtime subscriptions, and event listeners |
+| `stopSyncEngine()` | Tear down sync loop and subscriptions cleanly |
+| `runFullSync()` | Run a complete pull-then-push cycle |
+| `scheduleSyncPush()` | Trigger a debounced push of pending operations |
+| `getEngineConfig()` | Retrieve the current engine config (throws if not initialized) |
+| `validateSupabaseCredentials()` | Verify Supabase URL and anon key are valid |
+| `validateSchema()` | Validate all configured tables exist in Supabase |
 
-### Engine lifecycle
+### Database
 
 | Export | Description |
 |---|---|
-| `startSyncEngine()` | Start the sync loop, realtime subscriptions, and event listeners. |
-| `stopSyncEngine()` | Tear down everything cleanly. |
-| `scheduleSyncPush()` | Trigger a debounced push of pending operations. |
-| `runFullSync()` | Run a complete pull-then-push cycle. |
-| `clearLocalCache()` | Wipe all local application data. |
-| `clearPendingSyncQueue()` | Drop all pending outbound operations. |
+| `getDb()` | Get the Dexie database instance |
+| `resetDatabase()` | Drop and recreate the local IndexedDB database |
+| `clearLocalCache()` | Wipe all local application data |
+| `clearPendingSyncQueue()` | Drop all pending outbound operations |
+| `getSupabaseAsync()` | Async getter that waits for Supabase client initialization |
+| `resetSupabaseClient()` | Tear down and reinitialize the Supabase client |
 
-### Entity tracking
+### CRUD and Query Operations
 
 | Export | Description |
 |---|---|
-| `markEntityModified(table, id)` | Record that an entity was recently modified locally (prevents incoming realtime from overwriting). |
-| `onSyncComplete(callback)` | Register a callback invoked after each successful sync cycle. |
-
-### Auth Utilities
+| `engineCreate(table, data)` | Create a record locally and enqueue sync |
+| `engineUpdate(table, id, data)` | Update specific fields locally and enqueue sync |
+| `engineDelete(table, id)` | Soft-delete a record (tombstone) |
+| `engineIncrement(table, id, field, delta)` | Intent-preserving numeric increment |
+| `engineBatchWrite(operations)` | Execute multiple operations in a single sync push |
+| `engineGetOrCreate(table, id, defaults)` | Atomic get-or-create (upsert) |
+| `queryAll(table, options?)` | Query all rows from local IndexedDB |
+| `queryOne(table, id)` | Query a single row by ID |
+| `markEntityModified(table, id)` | Suppress incoming realtime overwrites for a recently modified entity |
+
+### Authentication -- Core
 
 | Export | Description |
 |---|---|
-| `signOut` | Full teardown: stops sync, clears caches, signs out of Supabase. |
-| `resendConfirmationEmail` | Resend signup confirmation email. |
-| `getUserProfile` / `updateProfile` | Profile read/write via Supabase user metadata. |
-| `verifyOtp` | Verify OTP token hash from confirmation email links. |
-| `getValidSession` | Get a non-expired Supabase session, or `null`. |
-| `resolveFirstName(session, offline, fallback?)` | Resolve display name from session or offline profile with configurable fallback. |
-| `resolveUserId(session, offline)` | Extract user UUID from session or offline credentials. |
-| `resolveAvatarInitial(session, offline, fallback?)` | Single uppercase initial for avatar display. |
+| `resolveAuthState()` | Determine current auth state (online, offline, or none) |
+| `signOut()` | Full teardown: stop sync, clear caches, sign out of Supabase |
+| `getValidSession()` | Get a non-expired Supabase session, or `null` |
+| `verifyOtp(tokenHash)` | Verify OTP token hash from email confirmation links |
+| `resendConfirmationEmail()` | Resend signup confirmation email |
+| `getUserProfile()` | Read profile from Supabase user metadata |
+| `updateProfile(data)` | Write profile to Supabase user metadata |
 
-### Single-user auth
-
-For personal apps that use a simplified PIN or password gate. Uses real Supabase email/password auth where the PIN is padded to meet minimum password length. Enable by setting `auth.singleUser` in the engine config.
+### Authentication -- Single-User
 
 | Export | Description |
 |---|---|
-| `isSingleUserSetUp()` | Check if initial setup is complete. |
-| `getSingleUserInfo()` | Get display info (profile, gate type) for the unlock screen. |
-| `setupSingleUser(gate, profile, email)` | First-time setup: create gate, Supabase email/password user, and store config. Returns `{ error, confirmationRequired }`. |
-| `unlockSingleUser(gate)` | Verify gate and restore session (online or offline). Returns `{ error, deviceVerificationRequired?, maskedEmail? }`. |
-| `completeSingleUserSetup()` | Called after the user confirms their email (when `emailConfirmation` is enabled). |
-| `completeDeviceVerification(tokenHash?)` | Called after the user completes device OTP verification (when `deviceVerification` is enabled). |
-| `lockSingleUser()` | Stop sync and reset auth state without destroying data. |
-| `changeSingleUserGate(oldGate, newGate)` | Change the PIN code or password. |
-| `updateSingleUserProfile(profile)` | Update profile in IndexedDB and Supabase metadata. |
-| `changeSingleUserEmail(newEmail)` | Request email change for single-user mode. Returns `{ error, confirmationRequired }`. |
-| `completeSingleUserEmailChange()` | Finalize email change: refresh session, update IndexedDB config and cached credentials. |
-| `resetSingleUser()` | Full reset: clear config, sign out, wipe local data. |
-| `padPin(pin)` | Pad a PIN to meet Supabase's minimum password length requirement. |
-
-### Queue
+| `setupSingleUser(gate, profile, email)` | First-time setup: create gate, Supabase user, and store config |
+| `unlockSingleUser(gate)` | Verify gate and restore session (online or offline) |
+| `lockSingleUser()` | Stop sync and reset auth state without destroying data |
+| `isSingleUserSetUp()` | Check if initial setup is complete |
+| `getSingleUserInfo()` | Get display info (profile, gate type) for the unlock screen |
+| `changeSingleUserGate(oldGate, newGate)` | Change PIN code or password |
+| `updateSingleUserProfile(profile)` | Update profile in IndexedDB and Supabase metadata |
+| `changeSingleUserEmail(newEmail)` | Request email change |
+| `completeSingleUserEmailChange()` | Finalize email change after confirmation |
+| `resetSingleUser()` | Full reset: clear config, sign out, wipe local data |
+| `padPin(pin)` | Pad a PIN to meet Supabase's minimum password length |
+
+### Authentication -- Device Verification
 
 | Export | Description |
 |---|---|
-| `queueSyncOperation(item)` | Enqueue a raw `SyncOperationItem`. |
-| `queueCreateOperation(table, id, payload)` | Enqueue entity creation. |
-| `queueDeleteOperation(table, id)` | Enqueue a soft delete. |
-| `coalescePendingOps()` | Compress the outbox in-place (called automatically before push). |
-| `getPendingSync()` / `getPendingEntityIds()` | Inspect the current outbox. |
+| `completeDeviceVerification(tokenHash?)` | Complete device OTP verification |
+| `sendDeviceVerification()` | Send device verification email |
+| `pollDeviceVerification()` | Poll for device verification completion |
+| `linkSingleUserDevice()` | Link current device to user after verification |
+| `getTrustedDevices()` | List all trusted devices for current user |
+| `removeTrustedDevice(deviceId)` | Remove a trusted device |
+| `getCurrentDeviceId()` | Get the stable device identifier |
+| `fetchRemoteGateConfig()` | Fetch gate config from Supabase for cross-device setup |
 
-### Conflict resolution
+### Authentication -- Display Utilities
 
 | Export | Description |
 |---|---|
-| `resolveConflicts(table, localEntity, remoteEntity, pendingOps)` | Three-tier field-level conflict resolver. Returns the merged entity. |
+| `resolveFirstName(session, offline, fallback?)` | Resolve display name from session or offline profile |
+| `resolveUserId(session, offline)` | Extract user UUID from session or offline credentials |
+| `resolveAvatarInitial(session, offline, fallback?)` | Single uppercase initial for avatar display |
 
-### Realtime
+### Reactive Stores
 
 | Export | Description |
 |---|---|
-| `startRealtimeSubscriptions()` / `stopRealtimeSubscriptions()` | Manage Supabase Realtime channels for all configured tables. |
-| `isRealtimeHealthy()` | Realtime connection health check. |
-| `wasRecentlyProcessedByRealtime(table, id)` | Guard against duplicate processing. |
-| `onRealtimeDataUpdate(callback)` | Register a handler for incoming realtime changes. |
+| `syncStatusStore` | Current `SyncStatus`, last sync time, and errors |
+| `authState` | Reactive auth state object (`mode`, `session`, `offlineProfile`, `isLoading`) |
+| `isAuthenticated` | Derived boolean for auth status |
+| `userDisplayInfo` | Derived display name and avatar info |
+| `isOnline` | Reactive boolean reflecting network state |
+| `remoteChangesStore` | Tracks entities recently changed by remote peers |
+| `createRecentChangeIndicator(table, id)` | Derived indicator for UI highlighting of remote changes |
+| `createPendingDeleteIndicator(table, id)` | Derived indicator for entities awaiting delete confirmation |
+| `onSyncComplete(callback)` | Register a callback invoked after each successful sync cycle |
+| `onRealtimeDataUpdate(callback)` | Register a handler for incoming realtime changes |
+
+### Store Factories
 
-### Stores (Svelte 5 compatible)
+| Export | Description |
+|---|---|
+| `createCollectionStore(table, options?)` | Live-updating list store from IndexedDB with filter and sort |
+| `createDetailStore(table, id)` | Single-record store by ID |
+
+### Realtime
 
 | Export | Description |
 |---|---|
-| `syncStatusStore` | Reactive store exposing current `SyncStatus`, last sync time, and errors. |
-| `remoteChangesStore` | Tracks which entities were recently changed by remote peers. |
-| `createRecentChangeIndicator(table, id)` | Derived indicator for UI highlighting of remote changes. |
-| `createPendingDeleteIndicator(table, id)` | Derived indicator for entities awaiting delete confirmation. |
-| `isOnline` | Reactive boolean reflecting network state. |
-| `authState` / `isAuthenticated` / `userDisplayInfo` | Reactive auth status stores. |
+| `startRealtimeSubscriptions()` | Start Supabase Realtime channels for all configured tables |
+| `stopRealtimeSubscriptions()` | Stop all Realtime channels |
+| `isRealtimeHealthy()` | Realtime connection health check |
+| `wasRecentlyProcessedByRealtime(table, id)` | Guard against duplicate processing |
 
-### Supabase client
+### Runtime Config
 
 | Export | Description |
 |---|---|
-| `supabase` | The configured `SupabaseClient` instance. |
-| `getSupabaseAsync()` | Async getter that waits for initialization. |
-| `resetSupabaseClient()` | Tear down and reinitialize the client. |
+| `initConfig()` | Initialize runtime configuration (fetches Supabase credentials from `/api/config`) |
+| `getConfig()` | Get current config |
+| `setConfig(config)` | Update runtime config |
+| `waitForConfig()` | Async getter that waits for config initialization |
+| `isConfigured()` | Check if config is initialized |
+| `clearConfigCache()` | Clear cached config |
+| `getDexieTableFor(supabaseName)` | Get the Dexie table name for a Supabase table name |
 
-### Runtime config
+### Diagnostics and Debug
 
 | Export | Description |
 |---|---|
-| `initConfig` / `getConfig` / `waitForConfig` / `setConfig` | Manage app-level runtime configuration (e.g., feature flags loaded from the server). |
-| `isConfigured()` / `clearConfigCache()` | Status and cache management. |
+| `getDiagnostics()` | Comprehensive runtime diagnostics (sync, queue, realtime, conflict, egress, network) |
+| `setDebugMode(enabled)` | Enable/disable debug logging |
+| `isDebugMode()` | Check if debug mode is active |
+| `debugLog` / `debugWarn` / `debugError` | Prefixed console helpers (gated by debug mode) |
+
+When debug mode is enabled, the engine exposes utilities on `window` using your configured prefix (e.g., `window.__myappSyncStats()`, `window.__myappEgress()`, `window.__myappTombstones()`, `window.__myappSync.forceFullSync()`).
 
 ### Utilities
 
 | Export | Description |
 |---|---|
-| `generateId()` | Generate a UUID. |
-| `now()` | Current ISO timestamp string. |
-| `calculateNewOrder(before, after)` | Fractional ordering helper for drag-and-drop reorder. |
-| `snakeToCamel(str)` | Convert a `snake_case` string to `camelCase` (also strips invalid characters). Used internally to derive Dexie table names from `supabaseName`. |
-| `getDeviceId()` | Stable per-device identifier (persisted in localStorage). |
-| `debugLog` / `debugWarn` / `debugError` | Prefixed console helpers (gated by `setDebugMode`). |
+| `generateId()` | Generate a UUID |
+| `now()` | Current ISO timestamp string |
+| `calculateNewOrder(before, after)` | Fractional ordering helper for drag-and-drop reorder |
+| `snakeToCamel(str)` | Convert `snake_case` to `camelCase` |
+| `getDeviceId()` | Stable per-device identifier (persisted in localStorage) |
 
-### Browser console debug utilities
+### SQL and TypeScript Generation
 
-When debug mode is enabled, the engine exposes utilities on the `window` object using the configured app prefix (e.g. `stellar`):
+| Export | Description |
+|---|---|
+| `generateSupabaseSQL(schema)` | Generate `CREATE TABLE` statements and RLS policies from schema |
+| `generateTypeScript(schema)` | Generate TypeScript interfaces from schema |
+| `generateMigrationSQL(oldSchema, newSchema)` | Generate `ALTER TABLE` migration SQL for schema changes |
 
-| Window property | Description |
+### Svelte Actions
+
+| Export | Description |
 |---|---|
-| `window.__<prefix>SyncStats()` | View sync cycle statistics (total cycles, recent cycle details, trigger types). |
-| `window.__<prefix>Egress()` | Monitor data transfer from Supabase (total bytes, per-table breakdown, recent cycles). |
-| `window.__<prefix>Tombstones()` | Check soft-deleted record counts across all tables. |
-| `window.__<prefix>Tombstones({ cleanup: true })` | Manually trigger tombstone cleanup. |
-| `window.__<prefix>Tombstones({ cleanup: true, force: true })` | Force server cleanup (bypasses 24-hour interval). |
-| `window.__<prefix>Sync.forceFullSync()` | Reset sync cursor, clear local data, and re-download everything from server. |
-| `window.__<prefix>Sync.resetSyncCursor()` | Clear the stored cursor so the next sync pulls all data. |
-| `window.__<prefix>Sync.sync()` | Trigger a manual sync cycle. |
-| `window.__<prefix>Sync.getStatus()` | View current sync cursor and pending operation count. |
-| `window.__<prefix>Sync.checkConnection()` | Test Supabase connectivity. |
-| `window.__<prefix>Sync.realtimeStatus()` | Check realtime connection state and health. |
-
-### Svelte actions
+| `remoteChangeAnimation` | `use:` action that animates an element when a remote change arrives |
+| `trackEditing` | Action that signals the engine a field is being actively edited (suppresses incoming overwrites) |
+| `triggerLocalAnimation` | Programmatically trigger the local-change animation on a node |
+| `truncateTooltip` | Action that shows a tooltip with full text when content is truncated |
+
+### Svelte Components (Optional - SvelteKit)
 
 | Export | Description |
 |---|---|
-| `remoteChangeAnimation` | Svelte `use:` action that animates an element when a remote change arrives. |
-| `trackEditing` | Action that signals the engine a field is being actively edited (suppresses incoming overwrites). |
-| `triggerLocalAnimation` | Programmatically trigger the local-change animation on a node. |
-| `truncateTooltip` | Action that shows a tooltip with full text when content is truncated via CSS overflow. |
+| `@prabhask5/stellar-engine/components/SyncStatus` | Animated sync-state indicator with tooltip and PWA refresh |
+| `@prabhask5/stellar-engine/components/DeferredChangesBanner` | Cross-device data conflict notification with diff preview |
+| `@prabhask5/stellar-engine/components/DemoBanner` | Demo mode indicator banner |
+
+### SvelteKit Helpers (Optional - SvelteKit)
 
-### Svelte components
+These require `svelte ^5.0.0` and `@sveltejs/kit` as peer dependencies.
 
 | Export | Description |
 |---|---|
-| `@prabhask5/stellar-engine/components/SyncStatus` | Full Svelte 5 component for animated sync-state indicator with tooltip and PWA refresh. Shows offline/syncing/synced/error/pending states with live indicator. |
-| `@prabhask5/stellar-engine/components/DeferredChangesBanner` | Full Svelte 5 component for cross-device data conflict notification. Shows when another device pushes changes while user is editing. Provides Update/Dismiss/Show Changes actions with diff preview. |
+| Layout load functions | `resolveAuthState` integration for `+layout.ts` |
+| Server handlers | Factory functions for API routes (`getServerConfig`, `createValidateHandler`, `deployToVercel`) |
+| Email confirmation | `handleEmailConfirmation()`, `broadcastAuthConfirmed()` |
+| SW lifecycle | `monitorSwLifecycle()`, `handleSwUpdate()`, `pollForNewServiceWorker()` |
+| Auth hydration | `hydrateAuthState()` for `+layout.svelte` |
 
-The `UpdatePrompt` component is **not** shipped as a stellar-engine export. Instead, it is generated by `stellar-engine install pwa` at `src/lib/components/UpdatePrompt.svelte` with TODO UI placeholders. The generated component imports `monitorSwLifecycle` and `handleSwUpdate` from `@prabhask5/stellar-engine/kit` for all SW lifecycle logic.
+### CRDT Collaborative Editing
 
-## Use cases
+| Export | Description |
+|---|---|
+| `openDocument(docId, pageId, options?)` | Open a collaborative document via Supabase Broadcast |
+| `closeDocument(docId)` | Close and clean up a document |
+| `createSharedText(doc)` | Create a shared Yjs text type |
+| `createBlockDocument(doc)` | Create a block-based document structure |
+| `updateCursor(docId, cursor)` | Update cursor position for presence |
+| `getCollaborators(docId)` | Get current collaborators |
+| `onCollaboratorsChange(docId, callback)` | Subscribe to collaborator changes |
+| `enableOffline(docId)` / `disableOffline(docId)` | Toggle offline persistence |
 
-- **Productivity and task management apps** -- offline-capable task boards, habit trackers, daily planners with cross-device sync.
-- **Notion-like editors** -- block-based documents where each block is a synced entity with field-level conflict resolution.
-- **Personal finance trackers** -- numeric merge fields handle concurrent balance adjustments across devices.
-- **File and asset management UIs** -- fractional ordering keeps drag-and-drop sort order consistent without rewriting every row.
+### Types
 
-## Demo Mode
+All TypeScript types are available from `@prabhask5/stellar-engine/types`:
 
-stellar-engine includes a built-in demo mode that provides a completely isolated sandbox for consumer apps. When active:
+`Session`, `SyncEngineConfig`, `TableConfig`, `AuthConfig`, `SchemaDefinition`, `SchemaTableConfig`, `FieldType`, `BatchOperation`, `SingleUserConfig`, `DemoConfig`, `SyncStatus`, `AuthMode`, `CRDTConfig`, and more.
 
-- **Separate database**: Uses `${name}_demo` IndexedDB — the real DB is never opened
-- **No Supabase**: Zero network requests to the backend
-- **Mock auth**: `authMode === 'demo'` — protected routes work with mock data only
-- **Auto-seeded**: Consumer's `seedData(db)` populates the demo DB on each page load
-- **Full isolation**: Page reload required to enter/exit (complete engine teardown)
+## Subpath exports
 
-### Quick Start
+Import only what you need:
 
-1. Define a `DemoConfig` with mock data and profile:
+| Subpath | Contents |
+|---|---|
+| `@prabhask5/stellar-engine` | Core: `initEngine`, `startSyncEngine`, `runFullSync`, `getDb`, `resetDatabase`, `getDiagnostics`, CRUD, auth, stores, and all re-exports |
+| `@prabhask5/stellar-engine/data` | CRUD + query operations + helpers |
+| `@prabhask5/stellar-engine/auth` | All auth functions |
+| `@prabhask5/stellar-engine/stores` | Reactive stores + store factories + event subscriptions |
+| `@prabhask5/stellar-engine/types` | All type exports |
+| `@prabhask5/stellar-engine/utils` | Utilities + debug + diagnostics + SQL/TS generation |
+| `@prabhask5/stellar-engine/actions` | Svelte `use:` actions |
+| `@prabhask5/stellar-engine/config` | Runtime config + `getDexieTableFor` |
+| `@prabhask5/stellar-engine/vite` | Vite plugin |
+| `@prabhask5/stellar-engine/kit` | SvelteKit helpers (optional) |
+| `@prabhask5/stellar-engine/crdt` | CRDT collaborative editing |
+| `@prabhask5/stellar-engine/components/SyncStatus` | Sync indicator component |
+| `@prabhask5/stellar-engine/components/DeferredChangesBanner` | Conflict banner component |
+| `@prabhask5/stellar-engine/components/DemoBanner` | Demo mode banner component |
+
+## Demo mode
+
+stellar-engine includes a built-in demo mode that provides a completely isolated sandbox. When active:
+
+- **Separate database** -- uses `${prefix}DB_demo` IndexedDB; the real database is never opened
+- **No Supabase** -- zero network requests to the backend
+- **Mock auth** -- `authMode === 'demo'`; protected routes work with mock data only
+- **Auto-seeded** -- your `seedData(db)` callback populates the demo database on each page load
+- **Full isolation** -- page reload required to enter/exit (complete engine teardown)
 
 ```ts
 import type { DemoConfig } from '@prabhask5/stellar-engine';
+import { setDemoMode, isDemoMode } from '@prabhask5/stellar-engine';
 
+// Define demo config in initEngine
 const demoConfig: DemoConfig = {
   seedData: async (db) => {
-    await db.table('items').bulkPut([{ id: '1', name: 'Sample', ... }]);
+    await db.table('projects').bulkPut([
+      { id: 'demo-1', name: 'Sample Project', order: 1 },
+    ]);
   },
   mockProfile: { email: 'demo@example.com', firstName: 'Demo', lastName: 'User' },
 };
-```
 
-2. Pass it to `initEngine()`:
+initEngine({ /* ...config */, demo: demoConfig });
 
-```ts
-initEngine({ ..., demo: demoConfig });
-```
-
-3. Toggle demo mode:
-
-```ts
-import { setDemoMode } from '@prabhask5/stellar-engine';
+// Toggle demo mode from your UI
 setDemoMode(true);
 window.location.href = '/'; // Full reload required
 ```
 
-The `stellar-engine install pwa` scaffolding generates demo files automatically.
-
-## CRDT Collaborative Editing (optional)
-
-The engine includes an optional Yjs-based CRDT subsystem for real-time collaborative document editing. Enable it by adding `crdt` to your `initEngine()` config:
-
-```ts
-initEngine({
-  prefix: 'myapp',
-  tables: [...],
-  database: { name: 'myapp-db', versions: [...] },
-  crdt: {
-    persistIntervalMs: 30000,     // Persist to Supabase every 30s
-    maxOfflineDocuments: 50,       // Max docs stored offline
-  },
-});
-```
-
-Then use the `@prabhask5/stellar-engine/crdt` subpath:
-
-```ts
-import {
-  openDocument, closeDocument,
-  createSharedText, createBlockDocument,
-  updateCursor, getCollaborators, onCollaboratorsChange,
-  enableOffline, disableOffline,
-  type YDoc, type YText,
-} from '@prabhask5/stellar-engine/crdt';
-
-// Open a collaborative document
-const provider = await openDocument('doc-1', 'page-1', {
-  offlineEnabled: true,
-  initialPresence: { name: 'Alice' },
-});
-
-// Use with any Yjs-compatible editor (Tiptap, BlockNote, etc.)
-const { content, meta } = createBlockDocument(provider.doc);
-meta.set('title', 'My Page');
-
-// Track collaborator cursors
-const unsub = onCollaboratorsChange('doc-1', (collaborators) => {
-  // Update avatar list, cursor positions, etc.
-});
-
-// Close when done
-await closeDocument('doc-1');
-```
-
-Key features:
-- **Real-time multi-user editing** via Supabase Broadcast (zero DB writes per keystroke)
-- **Cursor/presence awareness** via Supabase Presence
-- **Offline-first** with IndexedDB persistence and crash recovery
-- **Periodic Supabase persistence** (every 30s) for durable cross-device storage
-- **Cross-tab sync** via browser BroadcastChannel API (avoids network for same-device)
-- **Consumers never import yjs** -- all Yjs types are re-exported from the engine
-
 ## License
 
 Private -- not yet published under an open-source license.