@prabhask5/stellar-engine 1.1.18 → 1.2.1

package/dist/config.d.ts

@@ -23,37 +23,67 @@
 import type { SupabaseClient } from '@supabase/supabase-js';
 import type { Session } from '@supabase/supabase-js';
 import type Dexie from 'dexie';
-import type { SingleUserGateType } from './types';
+import type { SingleUserGateType, SchemaDefinition, AuthConfig } from './types';
+import type { CRDTConfig } from './crdt/types';
 import type { DemoConfig } from './demo';
 import { type DatabaseConfig } from './database';
 /**
  * Top-level configuration for the sync engine.
  *
- * Passed to {@link initEngine} at app startup. All fields except `tables`
- * and `prefix` have sensible defaults.
+ * Passed to {@link initEngine} at app startup. Supports two configuration modes:
+ *
+ * 1. **Schema-driven** (recommended) — Provide a `schema` object. The engine
+ *    auto-generates `tables`, Dexie stores, versioning, and database naming.
+ * 2. **Manual** (backward compat) — Provide explicit `tables` and `database`.
+ *
+ * The two modes are mutually exclusive (`schema` vs `tables` + `database`).
  *
  * @example
+ * // Schema-driven (new, recommended):
+ * initEngine({
+ *   prefix: 'myapp',
+ *   schema: {
+ *     goals: 'goal_list_id, order',
+ *     focus_settings: { singleton: true },
+ *   },
+ * });
+ *
+ * // Manual (backward compat):
  * initEngine({
  *   prefix: 'myapp',
- *   tables: [
- *     { supabaseName: 'goals', columns: 'id,title,target,current_value,...' },
- *   ],
- *   database: { name: 'myapp-db', versions: [{ version: 1, stores: { goals: 'id,user_id' } }] },
- *   syncDebounceMs: 1000,
+ *   tables: [...],
+ *   database: { name: 'myapp-db', versions: [...] },
  * });
  */
 export interface SyncEngineConfig {
-    /** Per-table sync configuration (required). */
+    /** Per-table sync configuration. Auto-populated when using `schema`. */
     tables: TableConfig[];
     /** Application prefix — used for localStorage keys, debug logging, etc. */
     prefix: string;
+    /**
+     * Declarative schema definition — replaces both `tables` and `database`.
+     *
+     * Each key is a Supabase table name (snake_case). Values are either a string
+     * of Dexie indexes or a {@link SchemaTableConfig} object for full control.
+     * Mutually exclusive with `tables` + `database`.
+     *
+     * @see {@link SchemaDefinition} for the full type definition
+     */
+    schema?: SchemaDefinition;
+    /**
+     * Override the auto-generated database name when using `schema`.
+     *
+     * By default, the database is named `${prefix}DB` (e.g., `stellarDB`).
+     * Use this to keep an existing database name for data continuity.
+     */
+    databaseName?: string;
     /** Provide a pre-created Dexie instance (backward compat). Mutually exclusive with `database`. */
     db?: Dexie;
     /** Provide a pre-created Supabase client (backward compat). Engine creates one internally if not provided. */
     supabase?: SupabaseClient;
     /** Engine creates and owns the Dexie instance when this is provided. */
     database?: DatabaseConfig;
-    /** Authentication configuration. */
+    /** Authentication configuration (nested/internal form). */
     auth?: {
         /** Single-user mode gate configuration. */
         singleUser?: {
@@ -104,6 +134,18 @@ export interface SyncEngineConfig {
      * @see {@link DemoConfig} for the configuration shape
      */
     demo?: DemoConfig;
+    /**
+     * CRDT collaborative editing configuration.
+     *
+     * When provided, enables the CRDT subsystem — creates IndexedDB tables for
+     * CRDT document storage and allows use of the `@prabhask5/stellar-engine/crdt` API.
+     * When omitted, no CRDT tables are created and CRDT imports will throw.
+     *
+     * Pass `true` as shorthand for `{}` (all defaults).
+     *
+     * @see {@link CRDTConfig} for available configuration options
+     */
+    crdt?: CRDTConfig | true;
 }
 /**
  * Per-table sync configuration.
@@ -154,7 +196,21 @@ export interface TableConfig {
  *   database: { name: 'myapp-db', versions: [...] },
  * });
  */
-export declare function initEngine(config: SyncEngineConfig): void;
+/**
+ * Input type for {@link initEngine}.
+ *
+ * Differs from {@link SyncEngineConfig} in two ways:
+ * - `tables` is optional (auto-generated when `schema` is provided)
+ * - `auth` accepts either the flat {@link AuthConfig} or the nested internal form
+ *
+ * The flat auth form is detected by the absence of a `singleUser` key and is
+ * normalized to the nested structure before being stored on the config singleton.
+ */
+export type InitEngineInput = Omit<SyncEngineConfig, 'tables' | 'auth'> & {
+    tables?: TableConfig[];
+    auth?: AuthConfig | SyncEngineConfig['auth'];
+};
+export declare function initEngine(config: InitEngineInput): void;
 /**
  * Wait for the database to be fully opened and upgraded.
  *

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAMzC,OAAO,EAAiC,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAOhF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IAEf,kGAAkG;IAClG,EAAE,CAAC,EAAE,KAAK,CAAC;IACX,8GAA8G;IAC9G,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAE1B,oCAAoC;IACpC,IAAI,CAAC,EAAE;QACL,2CAA2C;QAC3C,UAAU,CAAC,EAAE;YACX,QAAQ,EAAE,kBAAkB,CAAC;YAC7B,2CAA2C;YAC3C,UAAU,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;SACpB,CAAC;QACF,yEAAyE;QACzE,gBAAgB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACtF,2EAA2E;QAC3E,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClF,6DAA6D;QAC7D,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,2EAA2E;QAC3E,2BAA2B,CAAC,EAAE,MAAM,CAAC;QACrC,8EAA8E;QAC9E,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,sEAAsE;QACtE,kBAAkB,CAAC,EAAE;YACnB,OAAO,EAAE,OAAO,CAAC;YACjB,iEAAiE;YACjE,iBAAiB,CAAC,EAAE,MAAM,CAAC;SAC5B,CAAC;QACF,gEAAgE;QAChE,iBAAiB,CAAC,EAAE;YAClB,OAAO,EAAE,OAAO,CAAC;SAClB,CAAC;KACH,CAAC;IAEF,6EAA6E;IAC7E,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,KAAK,IAAI,CAAC;IACrE,6FAA6F;IAC7F,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAEzC,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,2GAA2G;IAC3G,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,4GAA4G;IAC5G,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAEnC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAW;IAC1B,kFAAkF;IAClF,YAAY,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,yEAAyE;IACzE,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,0EAA0E;IAC1E,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,0FAA0F;IAC1F,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAC3E;AAgBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAiCzD;AAMD;;;;;;;GAOG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAEzC;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,gBAAgB,CAKlD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAE3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAO5D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/config.js

@@ -25,7 +25,8 @@ import { _setDeviceIdPrefix } from './deviceId';
 import { _setClientPrefix } from './supabase/client';
 import { _setConfigPrefix } from './runtime/runtimeConfig';
 import { registerDemoConfig, _setDemoPrefix, isDemoMode } from './demo';
-import { createDatabase, _setManagedDb } from './database';
+import { createDatabase, _setManagedDb, SYSTEM_INDEXES, computeSchemaVersion } from './database';
+import { _initCRDT } from './crdt/config';
 import { snakeToCamel } from './utils';
 // =============================================================================
 // Module State
@@ -34,28 +35,32 @@ import { snakeToCamel } from './utils';
 let engineConfig = null;
 /** Promise that resolves when the database is fully opened and upgraded. */
 let _dbReady = null;
-// =============================================================================
-// Initialization
-// =============================================================================
-/**
- * Initialize the sync engine with the provided configuration.
- *
- * Must be called once at app startup, before any other engine function.
- * Propagates the `prefix` to all internal modules (debug, deviceId,
- * Supabase client, runtime config) and creates or registers the Dexie
- * database instance.
- *
- * @param config - The full engine configuration object.
- *
- * @example
- * // In your app's root layout or entry point:
- * initEngine({
- *   prefix: 'myapp',
- *   tables: [...],
- *   database: { name: 'myapp-db', versions: [...] },
- * });
- */
 export function initEngine(config) {
+    /* Normalize `crdt: true` shorthand to `crdt: {}`. */
+    if (config.crdt === true) {
+        config.crdt = {};
+    }
+    /* Normalize flat auth config to the nested structure used internally. */
+    if (config.auth) {
+        config.auth = normalizeAuthConfig(config.auth);
+    }
+    /*
+     * Schema-driven mode: auto-generate `tables` and `database` from the
+     * declarative schema definition.
+     */
+    if (config.schema) {
+        if (config.tables || config.database) {
+            throw new Error('initEngine: `schema` is mutually exclusive with `tables` and `database`. ' +
+                'Use either the schema-driven API or the manual API, not both.');
+        }
+        config.tables = generateTablesFromSchema(config.schema);
+        config.database = generateDatabaseFromSchema(config.schema, config.prefix, config.databaseName, !!config.crdt);
+    }
+    /* Validate that tables are configured (either manually or via schema). */
+    if (!config.tables || config.tables.length === 0) {
+        throw new Error('initEngine: No tables configured. Provide either `schema` or `tables`.');
+    }
+    /* At this point tables is guaranteed to be populated — safe to cast. */
     engineConfig = config;
     /* Propagate prefix to all internal modules that use localStorage keys. */
     if (config.prefix) {
@@ -69,13 +74,18 @@ export function initEngine(config) {
     if (config.demo) {
         registerDemoConfig(config.demo);
     }
+    /* Initialize CRDT subsystem if configured. */
+    if (config.crdt) {
+        _initCRDT(config.crdt, config.prefix);
+    }
     /* If demo mode is active, switch to a separate sandboxed database. */
     if (isDemoMode() && config.database) {
         config.database = { ...config.database, name: config.database.name + '_demo' };
     }
-    /* Handle database creation — either managed or provided. */
+    /* Handle database creation — either managed or provided.
+     * Pass crdtEnabled flag so CRDT IndexedDB tables are conditionally included. */
     if (config.database) {
-        _dbReady = createDatabase(config.database).then((db) => {
+        _dbReady = createDatabase(config.database, !!config.crdt).then((db) => {
             /* Store on config for backward compat (engine.ts reads config.db). */
             config.db = db;
         });
@@ -158,4 +168,235 @@ export function getTableColumns(supabaseName) {
     }
     return table.columns;
 }
+// =============================================================================
+// Schema → Config Generation
+// =============================================================================
+/**
+ * Generate `TableConfig[]` from a declarative {@link SchemaDefinition}.
+ *
+ * Each schema key becomes a `TableConfig` with:
+ * - `supabaseName` = the schema key (snake_case)
+ * - `columns` = `'*'` (SELECT all by default — no egress micro-optimization)
+ * - `ownershipFilter` = `'user_id'` (default, since RLS always filters by user)
+ * - `isSingleton`, `excludeFromConflict`, `numericMergeFields`, `onRemoteChange`
+ *   from the object form (if provided)
+ *
+ * @param schema - The declarative schema definition.
+ * @returns An array of `TableConfig` objects ready for engine consumption.
+ *
+ * @example
+ * generateTablesFromSchema({
+ *   goals: 'goal_list_id, order',
+ *   focus_settings: { singleton: true },
+ * });
+ * // → [
+ * //   { supabaseName: 'goals', columns: '*', ownershipFilter: 'user_id' },
+ * //   { supabaseName: 'focus_settings', columns: '*', ownershipFilter: 'user_id', isSingleton: true },
+ * // ]
+ */
+function generateTablesFromSchema(schema) {
+    const tables = [];
+    for (const [tableName, definition] of Object.entries(schema)) {
+        /* String form is sugar for { indexes: theString }. */
+        const config = typeof definition === 'string' ? { indexes: definition } : definition;
+        const tableConfig = {
+            supabaseName: tableName,
+            columns: config.columns || '*',
+            ownershipFilter: config.ownership || 'user_id'
+        };
+        if (config.singleton)
+            tableConfig.isSingleton = true;
+        if (config.excludeFromConflict)
+            tableConfig.excludeFromConflict = config.excludeFromConflict;
+        if (config.numericMergeFields)
+            tableConfig.numericMergeFields = config.numericMergeFields;
+        if (config.onRemoteChange)
+            tableConfig.onRemoteChange = config.onRemoteChange;
+        tables.push(tableConfig);
+    }
+    return tables;
+}
+/**
+ * Generate a `DatabaseConfig` from a declarative {@link SchemaDefinition}.
+ *
+ * Builds the Dexie store schema for each table by combining the app-specific
+ * indexes from the schema with the {@link SYSTEM_INDEXES} constant. Uses
+ * {@link computeSchemaVersion} for automatic version management.
+ *
+ * @param schema - The declarative schema definition.
+ * @param prefix - Application prefix for database naming and versioning.
+ * @param databaseName - Optional override for the database name.
+ * @param crdtEnabled - Whether the CRDT subsystem is enabled.
+ * @returns A `DatabaseConfig` ready for `createDatabase()`.
+ *
+ * @example
+ * generateDatabaseFromSchema(
+ *   { goals: 'goal_list_id, order' },
+ *   'stellar',
+ *   undefined,
+ *   false
+ * );
+ * // → {
+ * //   name: 'stellarDB',
+ * //   versions: [{ version: 1, stores: { goals: 'id, user_id, ..., goal_list_id, order' } }]
+ * // }
+ */
+function generateDatabaseFromSchema(schema, prefix, databaseName, crdtEnabled = false) {
+    const stores = {};
+    for (const [tableName, definition] of Object.entries(schema)) {
+        const config = typeof definition === 'string' ? { indexes: definition } : definition;
+        /* Determine the Dexie table name (camelCase by default, or explicit override). */
+        const dexieName = config.dexieName || snakeToCamel(tableName);
+        /* Merge system indexes with app-specific indexes. */
+        const appIndexes = (config.indexes || '').trim();
+        stores[dexieName] = appIndexes ? `${SYSTEM_INDEXES}, ${appIndexes}` : SYSTEM_INDEXES;
+    }
+    /* Compute auto-version based on the merged store schema.
+     * The CRDT flag affects the schema hash because CRDT system tables are merged
+     * by buildDexie() — if CRDT is toggled, the version should bump. */
+    const hashInput = crdtEnabled ? { ...stores, __crdt: 'enabled' } : stores;
+    const result = computeSchemaVersion(prefix, hashInput);
+    /*
+     * Build the versions array. When an upgrade is detected, declare BOTH
+     * the previous version and the current version so Dexie has a proper
+     * upgrade path (v(N-1) → vN). This avoids the UpgradeError that occurs
+     * when only the new version is declared and the browser already has the
+     * old version's IndexedDB schema.
+     *
+     * Dexie handles additive changes (new tables, new indexes) natively.
+     * For the previous version we use its original stores so Dexie can diff
+     * and apply the structural changes.
+     */
+    const versions = [];
+    if (result.previousStores && result.previousVersion) {
+        versions.push({ version: result.previousVersion, stores: result.previousStores });
+    }
+    /*
+     * Generate an upgrade callback when any table declares `renamedFrom`.
+     * The callback copies data from the old Dexie table to the new one,
+     * applying any `renamedColumns` transformations along the way.
+     */
+    const upgradeCallback = buildRenameUpgradeCallback(schema);
+    if (upgradeCallback) {
+        versions.push({ version: result.version, stores, upgrade: upgradeCallback });
+    }
+    else {
+        versions.push({ version: result.version, stores });
+    }
+    return {
+        name: databaseName || `${prefix}DB`,
+        versions
+    };
+}
+/**
+ * Build a Dexie upgrade callback that handles table renames.
+ *
+ * When a table declares `renamedFrom`, the callback copies all rows from
+ * the old table name to the new one, applying any `renamedColumns` field
+ * name transformations. Dexie's schema diff handles creating the new table
+ * and removing the old one — this callback only handles data migration.
+ *
+ * @param schema - The declarative schema definition.
+ * @returns An upgrade function, or `null` if no renames are declared.
+ * @internal
+ */
+function buildRenameUpgradeCallback(schema) {
+    /* Collect all rename operations. */
+    const renames = [];
+    for (const [tableName, definition] of Object.entries(schema)) {
+        const config = typeof definition === 'string' ? { indexes: definition } : definition;
+        if (!config.renamedFrom)
+            continue;
+        const oldDexie = config.dexieName ? config.dexieName : snakeToCamel(config.renamedFrom);
+        const newDexie = config.dexieName || snakeToCamel(tableName);
+        /* Only generate a callback if the Dexie name actually changed. */
+        if (oldDexie !== newDexie) {
+            renames.push({
+                oldDexie,
+                newDexie,
+                columnMap: config.renamedColumns
+            });
+        }
+    }
+    if (renames.length === 0)
+        return null;
+    return async (tx) => {
+        for (const { oldDexie, newDexie, columnMap } of renames) {
+            try {
+                const oldTable = tx.table(oldDexie);
+                const newTable = tx.table(newDexie);
+                const rows = await oldTable.toArray();
+                for (const row of rows) {
+                    /* Apply column renames if specified. */
+                    if (columnMap) {
+                        for (const [newCol, oldCol] of Object.entries(columnMap)) {
+                            if (oldCol in row) {
+                                row[newCol] = row[oldCol];
+                                delete row[oldCol];
+                            }
+                        }
+                    }
+                    await newTable.put(row);
+                }
+                /* Clear the old table — Dexie's schema diff will remove it. */
+                await oldTable.clear();
+            }
+            catch {
+                /* Old table may not exist (e.g., fresh install) — skip silently. */
+            }
+        }
+    };
+}
+/**
+ * Normalize an auth config to the internal nested structure.
+ *
+ * Detects whether the config is in the new flat form ({@link AuthConfig}) or
+ * the legacy nested form (has a `singleUser` key). Flat form is converted to
+ * nested; nested form is passed through unchanged.
+ *
+ * @param auth - The auth config (flat or nested).
+ * @returns The normalized nested auth config.
+ * @internal
+ */
+function normalizeAuthConfig(auth) {
+    if (!auth)
+        return auth;
+    /* Detect legacy nested form by the presence of `singleUser` key. */
+    if ('singleUser' in auth) {
+        return auth;
+    }
+    /* Flat form (AuthConfig) → convert to nested structure. */
+    const flat = auth;
+    const nested = {};
+    /* Map flat singleUser fields to nested singleUser object. */
+    const gateType = flat.gateType || 'code';
+    const codeLength = flat.codeLength || 6;
+    nested.singleUser = {
+        gateType,
+        ...(gateType === 'code' ? { codeLength } : {})
+    };
+    /* Map flat boolean flags to nested object structures. */
+    const emailConfirmation = flat.emailConfirmation !== undefined ? flat.emailConfirmation : true;
+    nested.emailConfirmation = { enabled: emailConfirmation };
+    const deviceVerification = flat.deviceVerification !== undefined ? flat.deviceVerification : true;
+    nested.deviceVerification = {
+        enabled: deviceVerification,
+        trustDurationDays: flat.trustDurationDays || 90
+    };
+    /* Pass through remaining fields with defaults. */
+    nested.confirmRedirectPath = flat.confirmRedirectPath || '/confirm';
+    nested.enableOfflineAuth =
+        flat.enableOfflineAuth !== undefined ? flat.enableOfflineAuth : true;
+    if (flat.sessionValidationIntervalMs !== undefined) {
+        nested.sessionValidationIntervalMs =
+            flat.sessionValidationIntervalMs;
+    }
+    if (flat.profileExtractor) {
+        nested.profileExtractor = flat.profileExtractor;
+    }
+    if (flat.profileToMetadata) {
+        nested.profileToMetadata = flat.profileToMetadata;
+    }
+    return nested;
+}
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/crdt/awareness.d.ts

@@ -0,0 +1,128 @@
+/**
+ * @fileoverview CRDT Presence / Awareness Management
+ *
+ * Bridges Supabase Presence ↔ local presence state for collaborative cursor
+ * and user tracking. Each open document has its own set of collaborators.
+ *
+ * Responsibilities:
+ *   - Tracking local cursor/selection state per document
+ *   - Debouncing cursor updates to avoid flooding the Presence channel
+ *   - Maintaining a list of active collaborators per document
+ *   - Providing subscription-based notifications for collaborator changes
+ *   - Deterministic color assignment from userId hash
+ *
+ * The Supabase Presence integration is handled through the same Realtime
+ * channel used for Broadcast. Presence state is tracked separately from
+ * Yjs document updates — they use different Supabase Realtime features
+ * (Presence vs Broadcast) on the same channel.
+ *
+ * @see {@link ./types.ts} for {@link UserPresenceState}
+ * @see {@link ./channel.ts} for the underlying Broadcast channel
+ * @see {@link ./provider.ts} for the lifecycle orchestrator
+ */
+import type { UserPresenceState } from './types';
+/**
+ * Assign a deterministic color to a user based on their userId.
+ *
+ * Uses a simple hash of the userId to index into the 12-color palette.
+ * The same userId always gets the same color, so collaborators appear
+ * consistent across sessions and devices.
+ *
+ * @param userId - The user's UUID.
+ * @returns A hex color string from the palette.
+ */
+export declare function assignColor(userId: string): string;
+/**
+ * Initialize presence tracking for a document.
+ *
+ * Called by the provider when a document is opened. Sets up the collaborator
+ * map and announces the local user's presence.
+ *
+ * @param documentId - The document to join.
+ * @param isConnected - Whether the Broadcast channel is connected.
+ * @param initialPresence - The local user's initial presence info.
+ * @internal
+ */
+export declare function joinPresence(documentId: string, isConnected: boolean, initialPresence: {
+    name: string;
+    avatarUrl?: string;
+}): void;
+/**
+ * Leave presence tracking for a document.
+ *
+ * Called by the provider when a document is closed. Cleans up the collaborator
+ * map and notifies listeners.
+ *
+ * @param documentId - The document to leave.
+ * @internal
+ */
+export declare function leavePresence(documentId: string): void;
+/**
+ * Handle a remote user joining the document.
+ *
+ * Called when a Supabase Presence `join` event is received.
+ *
+ * @param documentId - The document.
+ * @param presence - The remote user's presence state.
+ * @internal
+ */
+export declare function handlePresenceJoin(documentId: string, presence: UserPresenceState): void;
+/**
+ * Handle a remote user leaving the document.
+ *
+ * @param documentId - The document.
+ * @param userId - The user's UUID.
+ * @param deviceId - The user's device ID.
+ * @internal
+ */
+export declare function handlePresenceLeave(documentId: string, userId: string, deviceId: string): void;
+/**
+ * Update the local user's cursor and selection in a document.
+ *
+ * Debounced to `cursorDebounceMs` (default 50ms) to avoid flooding the
+ * Presence channel with rapid cursor movements.
+ *
+ * @param documentId - The document to update cursor for.
+ * @param cursor - Editor-specific cursor position (opaque to the engine).
+ * @param selection - Editor-specific selection range (opaque to the engine).
+ *
+ * @example
+ * // In your editor's cursor change handler:
+ * editor.on('selectionUpdate', ({ editor }) => {
+ *   updateCursor('doc-1', editor.state.selection.anchor, editor.state.selection);
+ * });
+ */
+export declare function updateCursor(documentId: string, cursor: unknown, selection?: unknown): void;
+/**
+ * Get the current list of collaborators for a document.
+ *
+ * Excludes the local user (they don't need to see their own cursor).
+ *
+ * @param documentId - The document to get collaborators for.
+ * @returns Array of presence states for remote collaborators.
+ *
+ * @example
+ * const collaborators = getCollaborators('doc-1');
+ * // [{ userId: '...', name: 'Alice', color: '#E57373', cursor: {...} }]
+ */
+export declare function getCollaborators(documentId: string): UserPresenceState[];
+/**
+ * Subscribe to collaborator changes for a document.
+ *
+ * The callback is invoked whenever a collaborator joins, leaves, or updates
+ * their cursor position. The callback receives the current list of remote
+ * collaborators (excluding the local user).
+ *
+ * @param documentId - The document to subscribe to.
+ * @param callback - Called with the updated collaborator list.
+ * @returns An unsubscribe function.
+ *
+ * @example
+ * const unsub = onCollaboratorsChange('doc-1', (collaborators) => {
+ *   avatarList = collaborators.map(c => ({ name: c.name, color: c.color }));
+ * });
+ * // Later:
+ * unsub();
+ */
+export declare function onCollaboratorsChange(documentId: string, callback: (collaborators: UserPresenceState[]) => void): () => void;
+//# sourceMappingURL=awareness.d.ts.map

package/dist/crdt/awareness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"awareness.d.ts","sourceRoot":"","sources":["../../src/crdt/awareness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AA6CjD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMlD;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,OAAO,EACpB,eAAe,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACpD,IAAI,CAQN;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAItD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAcxF;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAY9F;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,IAAI,CAgC3F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAmBxE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,CAAC,aAAa,EAAE,iBAAiB,EAAE,KAAK,IAAI,GACrD,MAAM,IAAI,CAcZ"}