@prabhask5/stellar-engine 1.1.7 → 1.1.9

package/README.md

@@ -81,7 +81,6 @@ initEngine({
   tables: [/* ... */],
   database: {/* ... */},
   auth: {
-    mode: 'single-user',
     singleUser: { gateType: 'code', codeLength: 4 },
     enableOfflineAuth: true,
     // emailConfirmation: { enabled: true },       // require email confirmation on setup
@@ -132,9 +131,9 @@ The command creates a full SvelteKit 2 + Svelte 5 project with:
 |------|---------------------------|--------------------------|
 | `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 `getUserProfile`, `onSyncComplete`, `authState` | Home page UI |
+| `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, admin check via `getConfig()`, `getValidSession()`, `isAdmin()` | — (fully managed) |
+| `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 |
@@ -168,7 +167,7 @@ Import only what you need via subpath exports:
 |---|---|
 | `@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 (`signIn`, `signUp`, `resolveAuthState`, `isAdmin`, `changeEmail`, `completeEmailChange`, single-user: `setupSingleUser`, `unlockSingleUser`, `lockSingleUser`, `completeSingleUserSetup`, `completeDeviceVerification`, `changeSingleUserEmail`, `completeSingleUserEmailChange`, `padPin`, 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.) |
@@ -300,27 +299,22 @@ Alternatively, you can provide a pre-created Dexie instance via the `db` config
 | `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
+### Auth Utilities
 
 | Export | Description |
 |---|---|
-| `signIn` / `signUp` / `signOut` | Supabase auth wrappers that also manage offline credential caching. |
-| `getSession` / `isSessionExpired` | Session inspection helpers. |
-| `changePassword` / `resendConfirmationEmail` | Account management. |
-| `changeEmail(newEmail)` | Request email change (sends confirmation to new address). Returns `{ error, confirmationRequired }`. |
-| `completeEmailChange()` | Finalize email change after confirmation. Refreshes session and updates cached credentials. |
+| `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. |
-
-### Offline auth
-
-| Export | Description |
-|---|---|
-| `cacheOfflineCredentials` / `getOfflineCredentials` / `verifyOfflineCredentials` / `clearOfflineCredentials` | Store and verify credentials locally for offline sign-in. |
-| `createOfflineSession` / `getValidOfflineSession` / `clearOfflineSession` | Manage offline session tokens in IndexedDB. |
+| `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. |
 
 ### 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.mode: 'single-user'` in the engine config.
+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.
 
 | Export | Description |
 |---|---|

package/dist/actions/remoteChange.d.ts

@@ -1,66 +1,191 @@
 /**
- * Remote Change Animation Action
+ * @fileoverview Remote Change Animation Action
  *
  * A Svelte action that automatically adds remote change animations to elements.
- * Use this on list items, cards, or any element that can be updated remotely.
+ * Use this on list items, cards, or any element that can be updated remotely
+ * (e.g., via Supabase Realtime subscriptions).
  *
  * The action detects the ACTION TYPE from the remote change and applies
- * the appropriate animation:
- * - 'create' → item-created (slide in with burst)
- * - 'delete' → item-deleting (slide out with fade)
- * - 'toggle' → checkbox-animating + completion-ripple
- * - 'increment' → counter-increment
- * - 'decrement' → counter-decrement
- * - 'reorder' → item-reordering
- * - 'rename' → text-changed
- * - 'update' → item-changed (default highlight)
- *
- * Usage:
+ * the appropriate CSS animation class:
+ *   - `'create'`    --> `item-created`       (slide in with burst)
+ *   - `'delete'`    --> `item-deleting`       (slide out with fade)
+ *   - `'toggle'`    --> `item-toggled`        (+ checkbox-animating + completion-ripple)
+ *   - `'increment'` --> `counter-increment`   (bump up)
+ *   - `'decrement'` --> `counter-decrement`   (bump down)
+ *   - `'reorder'`   --> `item-reordering`     (slide to new position)
+ *   - `'rename'`    --> `text-changed`        (highlight flash)
+ *   - `'update'`    --> `item-changed`        (default highlight)
+ *
+ * @example
  * ```svelte
  * <div use:remoteChangeAnimation={{ entityId: item.id, entityType: 'goals' }}>
  *   ...
  * </div>
  * ```
+ *
+ * @see {@link remoteChangeAnimation} for the main Svelte action
+ * @see {@link trackEditing} for deferred-change tracking on forms
+ * @see {@link triggerLocalAnimation} for programmatic local animations
  */
 import { type RemoteActionType } from '../stores/remoteChanges';
+/**
+ * Configuration options for the {@link remoteChangeAnimation} Svelte action.
+ */
 interface RemoteChangeOptions {
+    /** The unique identifier of the entity being watched (e.g., a row UUID). */
     entityId: string;
+    /** The entity type / table name (e.g., `'goals'`, `'tasks'`). */
     entityType: string;
+    /**
+     * Optional list of field names to watch. When provided, animations are
+     * only triggered if the remote change includes at least one of these
+     * fields (or the wildcard `'*'`). Omit to animate on any field change.
+     */
     fields?: string[];
+    /**
+     * Optional CSS class override. When set, this class is used instead of
+     * the default mapping from {@link ACTION_ANIMATION_MAP}.
+     */
     animationClass?: string;
+    /**
+     * Optional callback invoked when a remote action is detected.
+     * Useful for component-specific handling beyond CSS animations
+     * (e.g., updating local state, playing sounds, showing toasts).
+     *
+     * @param actionType - The type of remote action detected.
+     * @param fields - The list of fields that changed.
+     */
     onAction?: (actionType: RemoteActionType, fields: string[]) => void;
 }
+/**
+ * Svelte action that watches for remote changes on a specific entity and
+ * applies the appropriate CSS animation class to the host element.
+ *
+ * **Lifecycle:**
+ *   1. On mount, checks for a recent change that may have arrived before
+ *      the element was rendered (important for CREATE animations on new items).
+ *   2. Subscribes to the `remoteChangesStore` for future changes.
+ *   3. Subscribes to a pending-delete indicator for delete animations.
+ *   4. On update, re-subscribes if the entity identity changes.
+ *   5. On destroy, unsubscribes and cleans up CSS classes.
+ *
+ * @param node - The DOM element to animate.
+ * @param options - Configuration specifying which entity to watch.
+ * @returns A Svelte action lifecycle object with `update` and `destroy` methods.
+ *
+ * @example
+ * ```svelte
+ * <div use:remoteChangeAnimation={{ entityId: item.id, entityType: 'goals' }}>
+ *   {item.name}
+ * </div>
+ * ```
+ */
 export declare function remoteChangeAnimation(node: HTMLElement, options: RemoteChangeOptions): {
+    /**
+     * Called when the action's options change. If the entity identity
+     * (`entityId` or `entityType`) has changed, tears down old subscriptions
+     * and creates new ones for the updated entity.
+     *
+     * @param newOptions - The updated {@link RemoteChangeOptions}.
+     */
     update(newOptions: RemoteChangeOptions): void;
+    /**
+     * Cleanup handler — unsubscribes from all stores, removes the base
+     * CSS class, and clears the element from the animation tracking set.
+     */
     destroy(): void;
 };
 /**
- * Action for form elements that should track editing state.
- * Use this on modal forms with Save buttons to defer remote changes.
+ * Svelte action for form elements that should track editing state.
+ * Use this on modal forms with Save buttons to defer remote changes
+ * while the user is actively editing, preventing disruptive overwrites.
+ *
+ * When the form is destroyed (e.g., modal closes), any deferred changes
+ * are passed to the `onDeferredChanges` callback so the component can
+ * decide how to reconcile them.
  *
- * Usage:
+ * @example
  * ```svelte
  * <form use:trackEditing={{ entityId: item.id, entityType: 'goals', formType: 'manual-save' }}>
  *   ...
  * </form>
  * ```
  */
+/**
+ * Configuration options for the {@link trackEditing} Svelte action.
+ */
 interface TrackEditingOptions {
+    /** The unique identifier of the entity being edited. */
     entityId: string;
+    /** The entity type / table name (e.g., `'goals'`, `'tasks'`). */
     entityType: string;
+    /**
+     * The save behaviour of the form:
+     *   - `'auto-save'` — changes are saved immediately (e.g., inline editing).
+     *   - `'manual-save'` — changes are saved on explicit submit (e.g., modal form).
+     */
     formType: 'auto-save' | 'manual-save';
+    /**
+     * Optional list of field names this form edits. When provided, only
+     * remote changes to these fields are deferred; changes to other fields
+     * are applied immediately.
+     */
     fields?: string[];
+    /**
+     * Callback invoked when the form closes and there are deferred changes
+     * that need processing (e.g., conflict resolution, data refresh).
+     *
+     * @param changes - The array of deferred remote change objects.
+     */
     onDeferredChanges?: (changes: unknown[]) => void;
 }
+/**
+ * Svelte action that marks an entity as "being edited" in the remote changes
+ * store. While editing, incoming remote changes for the same entity are
+ * deferred instead of applied immediately.
+ *
+ * **Lifecycle:**
+ *   1. On mount, calls `remoteChangesStore.startEditing()` to begin deferral.
+ *   2. Periodically checks for deferred changes and toggles a CSS class
+ *      (`has-deferred-changes`) on the node for visual indication.
+ *   3. On update, re-registers if the entity identity changes.
+ *   4. On destroy, calls `remoteChangesStore.stopEditing()` and invokes
+ *      `onDeferredChanges` if any changes were deferred.
+ *
+ * @param node - The form DOM element.
+ * @param options - Configuration specifying which entity is being edited.
+ * @returns A Svelte action lifecycle object with `update` and `destroy` methods.
+ */
 export declare function trackEditing(node: HTMLElement, options: TrackEditingOptions): {
+    /**
+     * Called when the action's options change. If the entity identity
+     * changes, stops tracking the old entity and starts tracking the new one.
+     *
+     * @param newOptions - The updated {@link TrackEditingOptions}.
+     */
     update(newOptions: TrackEditingOptions): void;
+    /**
+     * Cleanup handler — stops the polling interval, removes CSS classes,
+     * stops editing in the store, and notifies the callback of any
+     * deferred changes that accumulated during the editing session.
+     */
     destroy(): void;
 };
 /**
  * Trigger a local action animation on an element.
- * Use this to make local actions animate the same way as remote actions.
  *
- * Usage in components:
+ * Use this to make local user actions (e.g., tapping a checkbox, incrementing
+ * a counter) animate with the same visual treatment as remote changes, giving
+ * the UI a consistent feel.
+ *
+ * For `increment` and `decrement` actions, rapid repeated invocations will
+ * restart the animation instead of being blocked — this allows the counter
+ * to visually "bump" on each tap.
+ *
+ * @param element - The DOM element to animate (or `null`, in which case this is a no-op).
+ * @param actionType - The type of animation to apply.
+ *
+ * @example
  * ```svelte
  * <script>
  *   import { triggerLocalAnimation } from '@prabhask5/stellar-engine';

package/dist/actions/remoteChange.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remoteChange.d.ts","sourceRoot":"","sources":["../../src/actions/remoteChange.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AAEjC,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IAEnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CACrE;AAiCD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,mBAAmB;uBAqH9D,mBAAmB;;EAkCzC;AAED;;;;;;;;;;GAUG;AAEH,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,WAAW,GAAG,aAAa,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CAClD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,mBAAmB;uBAqBrD,mBAAmB;;EAyBzC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,UAAU,EAAE,gBAAgB,GAC3B,IAAI,CA8DN"}
+{"version":3,"file":"remoteChange.d.ts","sourceRoot":"","sources":["../../src/actions/remoteChange.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AAMjC;;GAEG;AACH,UAAU,mBAAmB;IAC3B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IAEjB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CACrE;AAsDD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,mBAAmB;IAgJjF;;;;;;OAMG;uBACgB,mBAAmB;IA4BtC;;;OAGG;;EAQN;AAMD;;;;;;;;;;;;;;;GAeG;AAEH;;GAEG;AACH,UAAU,mBAAmB;IAC3B,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IAEjB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,QAAQ,EAAE,WAAW,GAAG,aAAa,CAAC;IAEtC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CAClD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,mBAAmB;IAwBxE;;;;;OAKG;uBACgB,mBAAmB;IAatC;;;;OAIG;;EAcN;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,UAAU,EAAE,gBAAgB,GAC3B,IAAI,CA8DN"}