stellar-drive 1.0.0

package/dist/debug.js

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview Debug Logging Utilities
+ *
+ * Provides opt-in debug logging gated by a localStorage flag. When debug
+ * mode is enabled (`localStorage.<prefix>_debug_mode === 'true'`), all
+ * debug calls forward to the browser console. When disabled, they are
+ * silently dropped — zero runtime cost.
+ *
+ * The prefix is configurable via {@link _setDebugPrefix} (set by
+ * {@link config.ts#initEngine}) so multiple engine instances on the same
+ * origin don't collide.
+ *
+ * @example
+ * // Enable debug mode from the browser console:
+ * localStorage.setItem('myapp_debug_mode', 'true');
+ *
+ * // Or programmatically:
+ * import { setDebugMode } from 'stellar-drive';
+ * setDebugMode(true);
+ */
+// =============================================================================
+// Internal State
+// =============================================================================
+/** Cached result of the localStorage check (avoids repeated reads). */
+let debugEnabled = null;
+/** Configurable prefix for the localStorage key (default: `'stellar'`). */
+let debugPrefix = 'stellar';
+// =============================================================================
+// Internal Helpers
+// =============================================================================
+/**
+ * Set the prefix used for the localStorage debug flag key.
+ *
+ * Called internally by {@link config.ts#initEngine} — not part of the
+ * public API.
+ *
+ * @param prefix - Application-specific prefix (e.g., `'myapp'`).
+ * @internal
+ */
+export function _setDebugPrefix(prefix) {
+    debugPrefix = prefix;
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Check whether debug mode is currently enabled.
+ *
+ * Reads `localStorage.<prefix>_debug_mode` on the first call and caches
+ * the result for subsequent calls. Returns `false` in SSR environments
+ * where `localStorage` is unavailable.
+ *
+ * @returns `true` if debug logging is active.
+ */
+export function isDebugMode() {
+    if (debugEnabled !== null)
+        return debugEnabled;
+    debugEnabled =
+        typeof localStorage !== 'undefined' &&
+            localStorage.getItem(`${debugPrefix}_debug_mode`) === 'true';
+    return debugEnabled;
+}
+/**
+ * Enable or disable debug mode at runtime.
+ *
+ * Persists the setting to localStorage so it survives page reloads.
+ *
+ * @param enabled - `true` to enable debug logging, `false` to disable.
+ */
+export function setDebugMode(enabled) {
+    debugEnabled = enabled;
+    localStorage.setItem(`${debugPrefix}_debug_mode`, enabled ? 'true' : 'false');
+}
+/**
+ * Log a debug message at the `console.log` level.
+ *
+ * No-op when debug mode is disabled.
+ *
+ * @param args - Arguments forwarded to `console.log`.
+ */
+export function debugLog(...args) {
+    if (isDebugMode())
+        console.log(...args);
+}
+/**
+ * Log a debug message at the `console.warn` level.
+ *
+ * No-op when debug mode is disabled.
+ *
+ * @param args - Arguments forwarded to `console.warn`.
+ */
+export function debugWarn(...args) {
+    if (isDebugMode())
+        console.warn(...args);
+}
+/**
+ * Log a debug message at the `console.error` level.
+ *
+ * No-op when debug mode is disabled.
+ *
+ * @param args - Arguments forwarded to `console.error`.
+ */
+export function debugError(...args) {
+    if (isDebugMode())
+        console.error(...args);
+}
+/**
+ * Unified debug logging function with configurable severity level.
+ *
+ * Replaces the individual `debugLog` / `debugWarn` / `debugError` calls
+ * when a single import is preferred.
+ *
+ * @param level - Console severity: `'log'`, `'warn'`, or `'error'`.
+ * @param args  - Arguments forwarded to the corresponding `console` method.
+ *
+ * @example
+ * debug('log', '[SYNC] Starting push...');
+ * debug('error', '[SYNC] Push failed:', error);
+ */
+export function debug(level, ...args) {
+    if (!isDebugMode())
+        return;
+    switch (level) {
+        case 'log':
+            console.log(...args);
+            break;
+        case 'warn':
+            console.warn(...args);
+            break;
+        case 'error':
+            console.error(...args);
+            break;
+    }
+}
+//# sourceMappingURL=debug.js.map

package/dist/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF,uEAAuE;AACvE,IAAI,YAAY,GAAmB,IAAI,CAAC;AAExC,2EAA2E;AAC3E,IAAI,WAAW,GAAG,SAAS,CAAC;AAE5B,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,WAAW,GAAG,MAAM,CAAC;AACvB,CAAC;AAED,gFAAgF;AAChF,aAAa;AACb,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW;IACzB,IAAI,YAAY,KAAK,IAAI;QAAE,OAAO,YAAY,CAAC;IAC/C,YAAY;QACV,OAAO,YAAY,KAAK,WAAW;YACnC,YAAY,CAAC,OAAO,CAAC,GAAG,WAAW,aAAa,CAAC,KAAK,MAAM,CAAC;IAC/D,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC3C,YAAY,GAAG,OAAO,CAAC;IACvB,YAAY,CAAC,OAAO,CAAC,GAAG,WAAW,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAG,IAAe;IACzC,IAAI,WAAW,EAAE;QAAE,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,GAAG,IAAe;IAC1C,IAAI,WAAW,EAAE;QAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,GAAG,IAAe;IAC3C,IAAI,WAAW,EAAE;QAAE,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,KAAK,CAAC,KAA+B,EAAE,GAAG,IAAe;IACvE,IAAI,CAAC,WAAW,EAAE;QAAE,OAAO;IAC3B,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,KAAK;YACR,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;YACrB,MAAM;QACR,KAAK,MAAM;YACT,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;YACtB,MAAM;QACR,KAAK,OAAO;YACV,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;YACvB,MAAM;IACV,CAAC;AACH,CAAC"}

package/dist/demo.d.ts

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview Demo Mode State Module
+ *
+ * Provides a completely isolated sandbox for consumer PWA apps. When demo mode
+ * is active, the app uses a separate Dexie database (`${name}_demo`), makes
+ * zero Supabase connections, and skips all sync/auth/email/device-verification
+ * flows. Writes go to the sandboxed DB and are dropped on page refresh (mock
+ * data is re-seeded).
+ *
+ * **Security model:**
+ * Demo mode does NOT "bypass" auth — it replaces the entire data layer.
+ * The real database is never opened. No Supabase client is created. If someone
+ * manually sets the localStorage flag on a real instance, they see an empty or
+ * seeded demo DB — there is no path to real user data.
+ *
+ * Callers of `setDemoMode()` must trigger a **full page reload**
+ * (`window.location.href`) to ensure complete engine teardown and
+ * reinitialization with the correct database.
+ *
+ * @module demo
+ * @see {@link config.ts} for demo DB name switching in `initEngine()`
+ * @see {@link engine.ts} for sync guards that check `isDemoMode()`
+ */
+import Dexie from 'dexie';
+/**
+ * Configuration for demo mode, provided by the consumer app.
+ *
+ * Contains a callback to seed mock data and a mock user profile for the
+ * demo session. Registered via `initEngine({ demo: demoConfig })`.
+ *
+ * @example
+ * ```ts
+ * const demoConfig: DemoConfig = {
+ *   seedData: async (db) => {
+ *     await db.table('items').bulkPut([
+ *       { id: '1', name: 'Sample Item', ... },
+ *     ]);
+ *   },
+ *   mockProfile: {
+ *     email: 'demo@example.com',
+ *     firstName: 'Demo',
+ *     lastName: 'User',
+ *   },
+ * };
+ * ```
+ */
+export interface DemoConfig {
+    /** Consumer callback that populates the demo Dexie DB with mock data. */
+    seedData: (db: Dexie) => Promise<void>;
+    /** Mock user profile for the demo session. */
+    mockProfile: {
+        email: string;
+        firstName: string;
+        lastName: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Check whether demo mode is currently active.
+ *
+ * SSR-safe: returns `false` on the server (no `localStorage` access).
+ *
+ * @returns `true` if the demo mode localStorage flag is set.
+ */
+export declare function isDemoMode(): boolean;
+/**
+ * Activate or deactivate demo mode.
+ *
+ * Sets a localStorage flag that is read during engine initialization.
+ * **The caller must trigger a full page reload** after calling this
+ * to ensure the engine reinitializes with the correct (demo or real) database.
+ *
+ * @param enabled - `true` to enter demo mode, `false` to exit.
+ *
+ * @example
+ * ```ts
+ * setDemoMode(true);
+ * window.location.href = '/';
+ * ```
+ */
+export declare function setDemoMode(enabled: boolean): void;
+/**
+ * Register the demo configuration.
+ *
+ * Called by `initEngine()` when the consumer provides a `demo` config.
+ *
+ * @param config - The demo configuration from the consumer app.
+ * @internal
+ */
+export declare function registerDemoConfig(config: DemoConfig): void;
+/**
+ * Get the currently registered demo configuration.
+ *
+ * @returns The demo config, or `null` if none is registered.
+ */
+export declare function getDemoConfig(): DemoConfig | null;
+/**
+ * Set the prefix used for the demo mode localStorage key.
+ *
+ * Called by `initEngine()` to propagate the app prefix.
+ *
+ * @param prefix - The application prefix (e.g. `'myapp'`).
+ * @internal
+ */
+export declare function _setDemoPrefix(prefix: string): void;
+/**
+ * Seed the demo database with mock data.
+ *
+ * Idempotent per page load: no-ops if data has already been seeded
+ * (prevents re-seeding on SvelteKit client-side navigations).
+ *
+ * Steps:
+ * 1. Check `_demoSeeded` flag — return if already seeded.
+ * 2. Clear all app tables (using engine config's table definitions).
+ * 3. Clear system tables (`syncQueue`, `conflictHistory`).
+ * 4. Call the consumer's `seedData(db)` callback.
+ * 5. Set `_demoSeeded = true`.
+ *
+ * @throws {Error} If no demo config is registered.
+ */
+export declare function seedDemoData(): Promise<void>;
+/**
+ * Delete the demo Dexie database entirely.
+ *
+ * Called when deactivating demo mode to clean up the sandboxed database.
+ * The caller should trigger a full page reload after this.
+ *
+ * @param dbName - The name of the demo database to delete (e.g. `'myapp-db_demo'`).
+ */
+export declare function cleanupDemoDatabase(dbName: string): Promise<void>;
+//# sourceMappingURL=demo.d.ts.map

package/dist/demo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo.d.ts","sourceRoot":"","sources":["../src/demo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAQ1B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,QAAQ,EAAE,CAAC,EAAE,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC,8CAA8C;IAC9C,WAAW,EAAE;QACX,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAmBD;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAGpC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAOlD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEnD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAgClD;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvE"}

package/dist/demo.js

@@ -0,0 +1,168 @@
+/**
+ * @fileoverview Demo Mode State Module
+ *
+ * Provides a completely isolated sandbox for consumer PWA apps. When demo mode
+ * is active, the app uses a separate Dexie database (`${name}_demo`), makes
+ * zero Supabase connections, and skips all sync/auth/email/device-verification
+ * flows. Writes go to the sandboxed DB and are dropped on page refresh (mock
+ * data is re-seeded).
+ *
+ * **Security model:**
+ * Demo mode does NOT "bypass" auth — it replaces the entire data layer.
+ * The real database is never opened. No Supabase client is created. If someone
+ * manually sets the localStorage flag on a real instance, they see an empty or
+ * seeded demo DB — there is no path to real user data.
+ *
+ * Callers of `setDemoMode()` must trigger a **full page reload**
+ * (`window.location.href`) to ensure complete engine teardown and
+ * reinitialization with the correct database.
+ *
+ * @module demo
+ * @see {@link config.ts} for demo DB name switching in `initEngine()`
+ * @see {@link engine.ts} for sync guards that check `isDemoMode()`
+ */
+import Dexie from 'dexie';
+import { getDb } from './database';
+import { getEngineConfig, getDexieTableFor } from './config';
+// =============================================================================
+// Module State
+// =============================================================================
+/** The registered demo configuration (set via `registerDemoConfig`). */
+let _demoConfig = null;
+/** Whether demo data has been seeded in this page load (prevents re-seeding). */
+let _demoSeeded = false;
+/** The app prefix, used to namespace the localStorage demo flag. */
+let _demoPrefix = '';
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Check whether demo mode is currently active.
+ *
+ * SSR-safe: returns `false` on the server (no `localStorage` access).
+ *
+ * @returns `true` if the demo mode localStorage flag is set.
+ */
+export function isDemoMode() {
+    if (typeof localStorage === 'undefined')
+        return false;
+    return localStorage.getItem(`${_demoPrefix}_demo_mode`) === 'true';
+}
+/**
+ * Activate or deactivate demo mode.
+ *
+ * Sets a localStorage flag that is read during engine initialization.
+ * **The caller must trigger a full page reload** after calling this
+ * to ensure the engine reinitializes with the correct (demo or real) database.
+ *
+ * @param enabled - `true` to enter demo mode, `false` to exit.
+ *
+ * @example
+ * ```ts
+ * setDemoMode(true);
+ * window.location.href = '/';
+ * ```
+ */
+export function setDemoMode(enabled) {
+    if (typeof localStorage === 'undefined')
+        return;
+    if (enabled) {
+        localStorage.setItem(`${_demoPrefix}_demo_mode`, 'true');
+    }
+    else {
+        localStorage.removeItem(`${_demoPrefix}_demo_mode`);
+    }
+}
+/**
+ * Register the demo configuration.
+ *
+ * Called by `initEngine()` when the consumer provides a `demo` config.
+ *
+ * @param config - The demo configuration from the consumer app.
+ * @internal
+ */
+export function registerDemoConfig(config) {
+    _demoConfig = config;
+}
+/**
+ * Get the currently registered demo configuration.
+ *
+ * @returns The demo config, or `null` if none is registered.
+ */
+export function getDemoConfig() {
+    return _demoConfig;
+}
+/**
+ * Set the prefix used for the demo mode localStorage key.
+ *
+ * Called by `initEngine()` to propagate the app prefix.
+ *
+ * @param prefix - The application prefix (e.g. `'myapp'`).
+ * @internal
+ */
+export function _setDemoPrefix(prefix) {
+    _demoPrefix = prefix;
+}
+/**
+ * Seed the demo database with mock data.
+ *
+ * Idempotent per page load: no-ops if data has already been seeded
+ * (prevents re-seeding on SvelteKit client-side navigations).
+ *
+ * Steps:
+ * 1. Check `_demoSeeded` flag — return if already seeded.
+ * 2. Clear all app tables (using engine config's table definitions).
+ * 3. Clear system tables (`syncQueue`, `conflictHistory`).
+ * 4. Call the consumer's `seedData(db)` callback.
+ * 5. Set `_demoSeeded = true`.
+ *
+ * @throws {Error} If no demo config is registered.
+ */
+export async function seedDemoData() {
+    if (_demoSeeded)
+        return;
+    if (!_demoConfig) {
+        throw new Error('No demo config registered. Pass `demo` to initEngine().');
+    }
+    const db = getDb();
+    const config = getEngineConfig();
+    /* Clear all app tables */
+    for (const table of config.tables) {
+        const dexieName = getDexieTableFor(table);
+        try {
+            await db.table(dexieName).clear();
+        }
+        catch {
+            /* Table may not exist in the demo DB — safe to ignore. */
+        }
+    }
+    /* Clear system tables */
+    for (const systemTable of ['syncQueue', 'conflictHistory']) {
+        try {
+            await db.table(systemTable).clear();
+        }
+        catch {
+            /* Safe to ignore if table doesn't exist. */
+        }
+    }
+    /* Call consumer's seed function */
+    await _demoConfig.seedData(db);
+    _demoSeeded = true;
+}
+/**
+ * Delete the demo Dexie database entirely.
+ *
+ * Called when deactivating demo mode to clean up the sandboxed database.
+ * The caller should trigger a full page reload after this.
+ *
+ * @param dbName - The name of the demo database to delete (e.g. `'myapp-db_demo'`).
+ */
+export async function cleanupDemoDatabase(dbName) {
+    try {
+        await Dexie.delete(dbName);
+    }
+    catch {
+        /* Ignore deletion errors — the DB may not exist. */
+    }
+}
+//# sourceMappingURL=demo.js.map

package/dist/demo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo.js","sourceRoot":"","sources":["../src/demo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAyC7D,gFAAgF;AAChF,eAAe;AACf,gFAAgF;AAEhF,wEAAwE;AACxE,IAAI,WAAW,GAAsB,IAAI,CAAC;AAE1C,iFAAiF;AACjF,IAAI,WAAW,GAAG,KAAK,CAAC;AAExB,oEAAoE;AACpE,IAAI,WAAW,GAAG,EAAE,CAAC;AAErB,gFAAgF;AAChF,aAAa;AACb,gFAAgF;AAEhF;;;;;;GAMG;AACH,MAAM,UAAU,UAAU;IACxB,IAAI,OAAO,YAAY,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IACtD,OAAO,YAAY,CAAC,OAAO,CAAC,GAAG,WAAW,YAAY,CAAC,KAAK,MAAM,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,IAAI,OAAO,YAAY,KAAK,WAAW;QAAE,OAAO;IAChD,IAAI,OAAO,EAAE,CAAC;QACZ,YAAY,CAAC,OAAO,CAAC,GAAG,WAAW,YAAY,EAAE,MAAM,CAAC,CAAC;IAC3D,CAAC;SAAM,CAAC;QACN,YAAY,CAAC,UAAU,CAAC,GAAG,WAAW,YAAY,CAAC,CAAC;IACtD,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAkB;IACnD,WAAW,GAAG,MAAM,CAAC;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,WAAW,GAAG,MAAM,CAAC;AACvB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,IAAI,WAAW;QAAE,OAAO;IACxB,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IAED,MAAM,EAAE,GAAG,KAAK,EAAE,CAAC;IACnB,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;IAEjC,0BAA0B;IAC1B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,CAAC;QACpC,CAAC;QAAC,MAAM,CAAC;YACP,0DAA0D;QAC5D,CAAC;IACH,CAAC;IAED,yBAAyB;IACzB,KAAK,MAAM,WAAW,IAAI,CAAC,WAAW,EAAE,iBAAiB,CAAC,EAAE,CAAC;QAC3D,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,4CAA4C;QAC9C,CAAC;IACH,CAAC;IAED,mCAAmC;IACnC,MAAM,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAE/B,WAAW,GAAG,IAAI,CAAC;AACrB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,MAAc;IACtD,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,oDAAoD;IACtD,CAAC;AACH,CAAC"}

package/dist/deviceId.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Stable Device Identifier Management
+ *
+ * Generates and persists a unique device identifier in localStorage. The ID
+ * survives page reloads and browser restarts, providing a stable "fingerprint"
+ * for the current browser profile.
+ *
+ * The device ID serves two critical roles in the sync engine:
+ *   1. **Echo suppression** — Realtime subscription payloads include `device_id`,
+ *      allowing the engine to skip changes that originated from this device.
+ *   2. **Deterministic conflict tiebreaker** — When two operations have identical
+ *      timestamps, the lexicographically lower `device_id` wins. This ensures
+ *      all devices resolve the same conflict the same way.
+ *
+ * The localStorage key is prefixed (e.g., `myapp_device_id`) so multiple engine
+ * instances on the same origin don't collide.
+ *
+ * @see {@link conflicts.ts#resolveByTimestamp} for the tiebreaker logic
+ * @see {@link realtime.ts#isOwnDeviceChange} for echo suppression
+ */
+/**
+ * Set the prefix used for the localStorage device ID key.
+ *
+ * Called internally by {@link config.ts#initEngine} — not part of the
+ * public API.
+ *
+ * @param prefix - Application-specific prefix (e.g., `'myapp'`).
+ * @internal
+ */
+export declare function _setDeviceIdPrefix(prefix: string): void;
+/**
+ * Get or create a stable device identifier for this browser/device.
+ *
+ * On the first call, generates a random UUID v4 and persists it to
+ * localStorage. Subsequent calls return the cached value.
+ *
+ * Returns `'ssr-placeholder'` in SSR contexts (no localStorage) — the
+ * placeholder is never used for real sync operations since the engine
+ * only runs client-side.
+ *
+ * @returns A UUID v4 string identifying this device.
+ *
+ * @example
+ * const id = getDeviceId(); // e.g., "a3f2b1c4-..."
+ */
+export declare function getDeviceId(): string;
+//# sourceMappingURL=deviceId.d.ts.map

package/dist/deviceId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deviceId.d.ts","sourceRoot":"","sources":["../src/deviceId.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAaH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,QAEhD;AAeD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAcpC"}

package/dist/deviceId.js

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Stable Device Identifier Management
+ *
+ * Generates and persists a unique device identifier in localStorage. The ID
+ * survives page reloads and browser restarts, providing a stable "fingerprint"
+ * for the current browser profile.
+ *
+ * The device ID serves two critical roles in the sync engine:
+ *   1. **Echo suppression** — Realtime subscription payloads include `device_id`,
+ *      allowing the engine to skip changes that originated from this device.
+ *   2. **Deterministic conflict tiebreaker** — When two operations have identical
+ *      timestamps, the lexicographically lower `device_id` wins. This ensures
+ *      all devices resolve the same conflict the same way.
+ *
+ * The localStorage key is prefixed (e.g., `myapp_device_id`) so multiple engine
+ * instances on the same origin don't collide.
+ *
+ * @see {@link conflicts.ts#resolveByTimestamp} for the tiebreaker logic
+ * @see {@link realtime.ts#isOwnDeviceChange} for echo suppression
+ */
+// =============================================================================
+// Internal State
+// =============================================================================
+/** Configurable prefix for the localStorage key (default: `'stellar'`). */
+let _deviceIdPrefix = 'stellar';
+// =============================================================================
+// Internal Helpers
+// =============================================================================
+/**
+ * Set the prefix used for the localStorage device ID key.
+ *
+ * Called internally by {@link config.ts#initEngine} — not part of the
+ * public API.
+ *
+ * @param prefix - Application-specific prefix (e.g., `'myapp'`).
+ * @internal
+ */
+export function _setDeviceIdPrefix(prefix) {
+    _deviceIdPrefix = prefix;
+}
+/**
+ * Build the full localStorage key for the device ID.
+ *
+ * @returns The prefixed key string (e.g., `'myapp_device_id'`).
+ */
+function getDeviceIdKey() {
+    return `${_deviceIdPrefix}_device_id`;
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Get or create a stable device identifier for this browser/device.
+ *
+ * On the first call, generates a random UUID v4 and persists it to
+ * localStorage. Subsequent calls return the cached value.
+ *
+ * Returns `'ssr-placeholder'` in SSR contexts (no localStorage) — the
+ * placeholder is never used for real sync operations since the engine
+ * only runs client-side.
+ *
+ * @returns A UUID v4 string identifying this device.
+ *
+ * @example
+ * const id = getDeviceId(); // e.g., "a3f2b1c4-..."
+ */
+export function getDeviceId() {
+    if (typeof localStorage === 'undefined') {
+        /* SSR context — return a placeholder that won't be used for sync. */
+        return 'ssr-placeholder';
+    }
+    let deviceId = localStorage.getItem(getDeviceIdKey());
+    if (!deviceId) {
+        deviceId = generateUUID();
+        localStorage.setItem(getDeviceIdKey(), deviceId);
+    }
+    return deviceId;
+}
+// =============================================================================
+// UUID Generation
+// =============================================================================
+/**
+ * Generate a UUID v4 (random UUID).
+ *
+ * Prefers the native `crypto.randomUUID()` API (available in modern browsers
+ * and Node 19+). Falls back to a manual implementation using `Math.random()`
+ * for older environments.
+ *
+ * @returns A lowercase UUID v4 string (e.g., `"550e8400-e29b-41d4-a716-446655440000"`).
+ */
+function generateUUID() {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    /*
+     * Fallback for older browsers that lack crypto.randomUUID().
+     * Replaces 'x' with a random hex digit and 'y' with a digit
+     * constrained to the UUID v4 variant bits (8, 9, a, or b).
+     */
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+//# sourceMappingURL=deviceId.js.map

package/dist/deviceId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deviceId.js","sourceRoot":"","sources":["../src/deviceId.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF,2EAA2E;AAC3E,IAAI,eAAe,GAAG,SAAS,CAAC;AAEhC,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,eAAe,GAAG,MAAM,CAAC;AAC3B,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc;IACrB,OAAO,GAAG,eAAe,YAAY,CAAC;AACxC,CAAC;AAED,gFAAgF;AAChF,aAAa;AACb,gFAAgF;AAEhF;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,WAAW;IACzB,IAAI,OAAO,YAAY,KAAK,WAAW,EAAE,CAAC;QACxC,qEAAqE;QACrE,OAAO,iBAAiB,CAAC;IAC3B,CAAC;IAED,IAAI,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAEtD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,QAAQ,GAAG,YAAY,EAAE,CAAC;QAC1B,YAAY,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,QAAQ,CAAC,CAAC;IACnD,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,SAAS,YAAY;IACnB,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACvD,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,OAAO,sCAAsC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;QACnE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;QAC1C,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;AACL,CAAC"}