@prabhask5/stellar-engine 1.0.3

package/README.md

@@ -0,0 +1,295 @@
+# @prabhask5/stellar-engine
+
+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.
+
+## 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
+
+## 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.
+- **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.
+
+## Quick start
+
+Install from GitHub Packages:
+
+```bash
+npm install @prabhask5/stellar-engine@^1.0.0
+```
+
+> Requires an `.npmrc` with `@stellar:registry=https://npm.pkg.github.com`.
+
+Initialize the engine at app startup (e.g., in a SvelteKit root `+layout.ts`):
+
+```ts
+import { initEngine, startSyncEngine, supabase } 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',
+      dexieTable: 'projects',
+      columns: 'id, name, created_at, updated_at, is_deleted, user_id',
+    },
+    // ...more tables
+  ],
+  database: {
+    name: 'MyAppDB',
+    versions: [
+      {
+        version: 1,
+        stores: {
+          projects: 'id, user_id, updated_at',
+          tasks: 'id, project_id, user_id, updated_at',
+        }
+      }
+    ]
+  },
+  auth: {
+    enableOfflineAuth: true,
+  },
+});
+
+await initConfig();
+const auth = await resolveAuthState();
+if (auth.authMode !== 'none') await startSyncEngine();
+```
+
+## Subpath exports
+
+Import only what you need via subpath exports:
+
+| Subpath | Contents |
+|---|---|
+| `@prabhask5/stellar-engine` | `initEngine`, `startSyncEngine`, `runFullSync`, `supabase`, `getDb`, `validateSupabaseCredentials` |
+| `@prabhask5/stellar-engine/data` | All engine CRUD + query operations (`engineCreate`, `engineUpdate`, etc.) |
+| `@prabhask5/stellar-engine/auth` | All auth functions (`signIn`, `signUp`, `resolveAuthState`, `isAdmin`, etc.) |
+| `@prabhask5/stellar-engine/stores` | Reactive stores + event subscriptions (`syncStatusStore`, `authState`, `onSyncComplete`, etc.) |
+| `@prabhask5/stellar-engine/types` | All type exports (`Session`, `SyncEngineConfig`, `BatchOperation`, etc.) |
+| `@prabhask5/stellar-engine/utils` | Utility functions (`generateId`, `now`, `calculateNewOrder`, `debug`, etc.) |
+| `@prabhask5/stellar-engine/actions` | Svelte `use:` actions (`remoteChangeAnimation`, `trackEditing`, `triggerLocalAnimation`) |
+| `@prabhask5/stellar-engine/config` | Runtime config (`initConfig`, `getConfig`, `setConfig`) |
+
+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. 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.
+
+**Dexie (IndexedDB)**
+
+When you provide a `database` config to `initEngine`, the engine creates and manages the Dexie instance for you. System tables (`syncQueue`, `conflictHistory`, `offlineCredentials`, `offlineSession`) are automatically merged into every schema version -- you only declare your application tables:
+
+```ts
+database: {
+  name: 'MyAppDB',
+  versions: [
+    {
+      version: 1,
+      stores: {
+        projects: 'id, user_id, updated_at',
+        tasks: 'id, project_id, user_id, updated_at',
+      }
+    }
+  ]
+}
+```
+
+Alternatively, you can provide a pre-created Dexie instance via the `db` config option for full control.
+
+## Architecture
+
+```
++---------------------+
+|   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)|
++---------------------+       +---------------------+
+```
+
+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.
+
+## API overview
+
+### Configuration
+
+| 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. |
+
+### Engine lifecycle
+
+| 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. |
+
+### Entity tracking
+
+| 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
+
+| Export | Description |
+|---|---|
+| `signIn` / `signUp` / `signOut` | Supabase auth wrappers that also manage offline credential caching. |
+| `getSession` / `isSessionExpired` | Session inspection helpers. |
+| `changePassword` / `resendConfirmationEmail` | Account management. |
+| `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. |
+
+### Queue
+
+| 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. |
+
+### Conflict resolution
+
+| Export | Description |
+|---|---|
+| `resolveConflicts(table, localEntity, remoteEntity, pendingOps)` | Three-tier field-level conflict resolver. Returns the merged entity. |
+
+### Realtime
+
+| 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. |
+
+### Stores (Svelte 5 compatible)
+
+| 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. |
+
+### Supabase client
+
+| Export | Description |
+|---|---|
+| `supabase` | The configured `SupabaseClient` instance. |
+| `getSupabaseAsync()` | Async getter that waits for initialization. |
+| `resetSupabaseClient()` | Tear down and reinitialize the client. |
+
+### Runtime config
+
+| 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. |
+
+### Utilities
+
+| Export | Description |
+|---|---|
+| `generateId()` | Generate a UUID. |
+| `now()` | Current ISO timestamp string. |
+| `calculateNewOrder(before, after)` | Fractional ordering helper for drag-and-drop reorder. |
+| `getDeviceId()` | Stable per-device identifier (persisted in localStorage). |
+| `debugLog` / `debugWarn` / `debugError` | Prefixed console helpers (gated by `setDebugMode`). |
+
+### Browser console debug utilities
+
+When debug mode is enabled, the engine exposes utilities on the `window` object using the configured app prefix (e.g. `stellar`):
+
+| Window property | 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
+
+| 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. |
+
+## Use cases
+
+- **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.
+
+## License
+
+Private -- not yet published under an open-source license.

package/dist/actions/remoteChange.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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.
+ *
+ * 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:
+ * ```svelte
+ * <div use:remoteChangeAnimation={{ entityId: item.id, entityType: 'goals' }}>
+ *   ...
+ * </div>
+ * ```
+ */
+import { type RemoteActionType } from '../stores/remoteChanges';
+interface RemoteChangeOptions {
+    entityId: string;
+    entityType: string;
+    fields?: string[];
+    animationClass?: string;
+    onAction?: (actionType: RemoteActionType, fields: string[]) => void;
+}
+export declare function remoteChangeAnimation(node: HTMLElement, options: RemoteChangeOptions): {
+    update(newOptions: RemoteChangeOptions): void;
+    destroy(): void;
+};
+/**
+ * Action for form elements that should track editing state.
+ * Use this on modal forms with Save buttons to defer remote changes.
+ *
+ * Usage:
+ * ```svelte
+ * <form use:trackEditing={{ entityId: item.id, entityType: 'goals', formType: 'manual-save' }}>
+ *   ...
+ * </form>
+ * ```
+ */
+interface TrackEditingOptions {
+    entityId: string;
+    entityType: string;
+    formType: 'auto-save' | 'manual-save';
+    fields?: string[];
+    onDeferredChanges?: (changes: unknown[]) => void;
+}
+export declare function trackEditing(node: HTMLElement, options: TrackEditingOptions): {
+    update(newOptions: TrackEditingOptions): void;
+    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:
+ * ```svelte
+ * <script>
+ *   import { triggerLocalAnimation } from '@prabhask5/stellar-engine';
+ *   let element: HTMLElement;
+ *
+ *   function handleToggle() {
+ *     triggerLocalAnimation(element, 'toggle');
+ *     onToggle?.();
+ *   }
+ * </script>
+ * <div bind:this={element}>...</div>
+ * ```
+ */
+export declare function triggerLocalAnimation(element: HTMLElement | null, actionType: RemoteActionType): void;
+export {};
+//# sourceMappingURL=remoteChange.d.ts.map

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

@@ -0,0 +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"}

package/dist/actions/remoteChange.js

@@ -0,0 +1,300 @@
+/**
+ * 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.
+ *
+ * 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:
+ * ```svelte
+ * <div use:remoteChangeAnimation={{ entityId: item.id, entityType: 'goals' }}>
+ *   ...
+ * </div>
+ * ```
+ */
+import { remoteChangesStore, createRecentChangeIndicator, createPendingDeleteIndicator } from '../stores/remoteChanges';
+/**
+ * Map action types to CSS animation classes
+ */
+const ACTION_ANIMATION_MAP = {
+    create: 'item-created',
+    delete: 'item-deleting',
+    toggle: 'item-toggled',
+    increment: 'counter-increment',
+    decrement: 'counter-decrement',
+    reorder: 'item-reordering',
+    rename: 'text-changed',
+    update: 'item-changed'
+};
+/**
+ * Animation durations for cleanup (ms)
+ */
+const ACTION_DURATION_MAP = {
+    create: 600,
+    delete: 500,
+    toggle: 600,
+    increment: 400,
+    decrement: 400,
+    reorder: 400,
+    rename: 700,
+    update: 1600
+};
+// Track currently animating elements to prevent overlapping animations
+const animatingElements = new WeakSet();
+export function remoteChangeAnimation(node, options) {
+    let { entityId, entityType, fields, animationClass, onAction } = options;
+    // Add base class for styling hooks
+    node.classList.add('syncable-item');
+    // Helper function to apply animation
+    function applyAnimation(change) {
+        // If fields are specified, only animate if those fields changed
+        if (fields && fields.length > 0) {
+            const fieldsList = fields; // Capture for closure
+            const hasRelevantChange = change.fields.some((f) => f === '*' || fieldsList.includes(f));
+            if (!hasRelevantChange)
+                return;
+        }
+        // Prevent overlapping animations on the same element
+        if (animatingElements.has(node))
+            return;
+        animatingElements.add(node);
+        // Determine animation class based on action type
+        const actionType = change.actionType;
+        const cssClass = animationClass || ACTION_ANIMATION_MAP[actionType] || 'item-changed';
+        const duration = ACTION_DURATION_MAP[actionType] || 1600;
+        // Call action callback if provided (for component-specific handling)
+        if (onAction) {
+            onAction(actionType, change.fields);
+        }
+        // Apply animation class
+        node.classList.add(cssClass);
+        // For toggle actions, also add checkbox animation to child checkbox elements
+        if (actionType === 'toggle') {
+            const checkbox = node.querySelector('.checkbox, [class*="checkbox"]');
+            if (checkbox) {
+                checkbox.classList.add('checkbox-animating');
+                setTimeout(() => checkbox.classList.remove('checkbox-animating'), 500);
+            }
+            // Add completion ripple effect
+            const ripple = document.createElement('span');
+            ripple.className = 'completion-ripple';
+            node.appendChild(ripple);
+            setTimeout(() => ripple.remove(), 700);
+        }
+        // For increment/decrement, animate the counter element
+        if (actionType === 'increment' || actionType === 'decrement') {
+            const counter = node.querySelector('[class*="value"], [class*="counter"], [class*="current"]');
+            if (counter) {
+                counter.classList.add(cssClass);
+                setTimeout(() => counter.classList.remove(cssClass), duration);
+            }
+        }
+        // For delete animations, don't remove the class — the element will be
+        // removed from DOM after the animation. Removing it early causes the item
+        // to briefly reappear between animation end and DOM removal.
+        if (actionType === 'delete')
+            return;
+        // Remove class after animation completes
+        const handleAnimationEnd = () => {
+            node.classList.remove(cssClass);
+            animatingElements.delete(node);
+            node.removeEventListener('animationend', handleAnimationEnd);
+        };
+        node.addEventListener('animationend', handleAnimationEnd);
+        // Fallback removal in case animationend doesn't fire
+        setTimeout(() => {
+            node.classList.remove(cssClass);
+            animatingElements.delete(node);
+        }, duration + 100);
+    }
+    // Check for recent change immediately on mount (important for CREATE animations)
+    // This handles the case where the element mounts after a remote INSERT
+    const initialChange = remoteChangesStore.getRecentChange(entityId, entityType);
+    if (initialChange) {
+        // Use requestAnimationFrame to ensure DOM is ready
+        requestAnimationFrame(() => {
+            applyAnimation(initialChange);
+        });
+    }
+    // Create derived stores to watch for future changes and pending deletes
+    let changeIndicator = createRecentChangeIndicator(entityId, entityType);
+    let deleteIndicator = createPendingDeleteIndicator(entityId, entityType);
+    // Track the current unsubscribe functions
+    let unsubscribeChange = changeIndicator.subscribe((change) => {
+        // Skip if no change or if this is the same change we already animated on mount
+        if (!change)
+            return;
+        if (initialChange && change.timestamp === initialChange.timestamp)
+            return;
+        applyAnimation(change);
+    });
+    // Watch for pending deletes to apply delete animation
+    let unsubscribeDelete = deleteIndicator.subscribe((isPendingDelete) => {
+        if (isPendingDelete) {
+            // Apply delete animation immediately
+            const deleteClass = ACTION_ANIMATION_MAP['delete'];
+            node.classList.add(deleteClass);
+            // Call action callback if provided
+            if (onAction) {
+                onAction('delete', ['*']);
+            }
+        }
+    });
+    return {
+        update(newOptions) {
+            // If entity changed, re-subscribe with new entity
+            if (newOptions.entityId !== entityId || newOptions.entityType !== entityType) {
+                unsubscribeChange();
+                unsubscribeDelete();
+                entityId = newOptions.entityId;
+                entityType = newOptions.entityType;
+                fields = newOptions.fields;
+                animationClass = newOptions.animationClass;
+                onAction = newOptions.onAction;
+                changeIndicator = createRecentChangeIndicator(entityId, entityType);
+                deleteIndicator = createPendingDeleteIndicator(entityId, entityType);
+                unsubscribeChange = changeIndicator.subscribe((change) => {
+                    if (!change)
+                        return;
+                    applyAnimation(change);
+                });
+                unsubscribeDelete = deleteIndicator.subscribe((isPendingDelete) => {
+                    if (isPendingDelete) {
+                        const deleteClass = ACTION_ANIMATION_MAP['delete'];
+                        node.classList.add(deleteClass);
+                        if (onAction) {
+                            onAction('delete', ['*']);
+                        }
+                    }
+                });
+            }
+        },
+        destroy() {
+            unsubscribeChange();
+            unsubscribeDelete();
+            node.classList.remove('syncable-item');
+            animatingElements.delete(node);
+        }
+    };
+}
+export function trackEditing(node, options) {
+    const { entityId, entityType, formType, fields, onDeferredChanges } = options;
+    // Start tracking when the element mounts
+    remoteChangesStore.startEditing(entityId, entityType, formType, fields);
+    // Check for deferred changes indicator
+    const updateDeferredIndicator = () => {
+        const hasDeferred = remoteChangesStore.hasDeferredChanges(entityId, entityType);
+        if (hasDeferred) {
+            node.classList.add('has-deferred-changes');
+        }
+        else {
+            node.classList.remove('has-deferred-changes');
+        }
+    };
+    // Check periodically for deferred changes
+    const interval = setInterval(updateDeferredIndicator, 1000);
+    updateDeferredIndicator();
+    return {
+        update(newOptions) {
+            // If entity changed, stop old tracking and start new
+            if (newOptions.entityId !== entityId || newOptions.entityType !== entityType) {
+                remoteChangesStore.stopEditing(entityId, entityType);
+                remoteChangesStore.startEditing(newOptions.entityId, newOptions.entityType, newOptions.formType, newOptions.fields);
+            }
+        },
+        destroy() {
+            clearInterval(interval);
+            node.classList.remove('has-deferred-changes');
+            // Stop tracking and get any deferred changes
+            const deferredChanges = remoteChangesStore.stopEditing(entityId, entityType);
+            // Notify callback if there are deferred changes
+            if (deferredChanges.length > 0 && onDeferredChanges) {
+                onDeferredChanges(deferredChanges);
+            }
+        }
+    };
+}
+/**
+ * Trigger a local action animation on an element.
+ * Use this to make local actions animate the same way as remote actions.
+ *
+ * Usage in components:
+ * ```svelte
+ * <script>
+ *   import { triggerLocalAnimation } from '@prabhask5/stellar-engine';
+ *   let element: HTMLElement;
+ *
+ *   function handleToggle() {
+ *     triggerLocalAnimation(element, 'toggle');
+ *     onToggle?.();
+ *   }
+ * </script>
+ * <div bind:this={element}>...</div>
+ * ```
+ */
+export function triggerLocalAnimation(element, actionType) {
+    if (!element)
+        return;
+    const cssClass = ACTION_ANIMATION_MAP[actionType] || 'item-changed';
+    const duration = ACTION_DURATION_MAP[actionType] || 1600;
+    // For increment/decrement, restart animation on rapid taps instead of blocking
+    if (actionType === 'increment' || actionType === 'decrement') {
+        if (animatingElements.has(element)) {
+            // Force restart: remove class, trigger reflow, re-add
+            element.classList.remove(cssClass);
+            void element.offsetWidth;
+        }
+    }
+    else {
+        // Prevent overlapping animations for other types
+        if (animatingElements.has(element))
+            return;
+    }
+    animatingElements.add(element);
+    // Apply animation class
+    element.classList.add(cssClass);
+    // For toggle actions, also animate checkbox elements
+    if (actionType === 'toggle') {
+        const checkbox = element.querySelector('.checkbox, [class*="checkbox"]');
+        if (checkbox) {
+            checkbox.classList.add('checkbox-animating');
+            setTimeout(() => checkbox.classList.remove('checkbox-animating'), 500);
+        }
+        // Add completion ripple effect
+        const ripple = document.createElement('span');
+        ripple.className = 'completion-ripple';
+        element.appendChild(ripple);
+        setTimeout(() => ripple.remove(), 700);
+    }
+    // For increment/decrement, animate the counter element
+    if (actionType === 'increment' || actionType === 'decrement') {
+        const counter = element.querySelector('[class*="value"], [class*="counter"], [class*="current"]');
+        if (counter) {
+            counter.classList.add(cssClass);
+            setTimeout(() => counter.classList.remove(cssClass), duration);
+        }
+    }
+    // Remove class after animation completes
+    const handleAnimationEnd = () => {
+        element.classList.remove(cssClass);
+        animatingElements.delete(element);
+        element.removeEventListener('animationend', handleAnimationEnd);
+    };
+    element.addEventListener('animationend', handleAnimationEnd);
+    // Fallback removal
+    setTimeout(() => {
+        element.classList.remove(cssClass);
+        animatingElements.delete(element);
+    }, duration + 100);
+}
+//# sourceMappingURL=remoteChange.js.map