@prabhask5/stellar-engine 1.1.6 → 1.1.8

package/README.md

@@ -18,7 +18,6 @@ A local-first, offline-capable sync engine for **SvelteKit + Supabase + Dexie**
 - **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.
-- **Email** -- optional SMTP email sending for share link invitations and notifications, with credential validation.
 
 ## Quick start
 
@@ -106,31 +105,61 @@ if (!auth.singleUserSetUp) {
 }
 ```
 
-### Email (optional)
+## Install PWA Command
 
-Send emails via SMTP for share link invitations:
+Scaffold a complete offline-first PWA project:
 
-```ts
-import { sendEmail, validateSmtpCredentials } from '@prabhask5/stellar-engine/email';
-
-// Validate SMTP credentials
-const { valid, error } = await validateSmtpCredentials({
-  smtpHost: 'smtp.example.com',
-  smtpPort: 587,
-  smtpUser: 'user@example.com',
-  smtpPass: 'password',
-  fromEmail: 'noreply@example.com',
-  fromName: 'My App'
-});
-
-// Send an email
-const result = await sendEmail(config, {
-  to: 'recipient@example.com',
-  subject: 'You have been invited',
-  html: '<p>Click here to view the shared note.</p>'
-});
+```bash
+npx @prabhask5/stellar-engine install pwa --name "My App" --short_name "App" --prefix "myapp" [--description "..."]
 ```
 
+### What it generates
+
+The command creates a full SvelteKit 2 + Svelte 5 project with:
+
+**Configuration files (8):** `vite.config.ts`, `tsconfig.json`, `svelte.config.js`, `eslint.config.js`, `.prettierrc`, `.prettierignore`, `knip.json`, `.gitignore`
+
+**Documentation (3):** `README.md`, `ARCHITECTURE.md`, `FRAMEWORKS.md`
+
+**Static assets (13):** `manifest.json`, `offline.html`, placeholder SVG icons (app, dark, maskable, favicon, monochrome, splash, apple-touch), email template placeholders (signup, change-email, device-verification)
+
+**Database (1):** `supabase-schema.sql` with helper functions, example table pattern, and `trusted_devices` table
+
+**Source files (2):** `src/app.html` (PWA-ready with iOS meta tags, landscape blocker, zoom prevention, SW registration), `src/app.d.ts`
+
+**Route files (16):**
+| File | What stellar-engine manages | What you customize (TODO) |
+|------|---------------------------|--------------------------|
+| `src/routes/+layout.ts` | Auth resolution, config init, sync engine startup via `resolveAuthState()`, `initConfig()`, `startSyncEngine()` | `initEngine()` config with your database schema |
+| `src/routes/+layout.svelte` | Auth state hydration via `hydrateAuthState()` | App shell (navbar, tab bar, overlays) |
+| `src/routes/+page.svelte` | Imports `resolveFirstName`, `onSyncComplete`, `authState`; derives `firstName` reactively | Home page UI |
+| `src/routes/+error.svelte` | — | Error page UI |
+| `src/routes/setup/+page.ts` | Config check, session validation, admin check via `getConfig()`, `getValidSession()`, `isAdmin()` | — (fully managed) |
+| `src/routes/setup/+page.svelte` | Imports `setConfig`, `isOnline`, `pollForNewServiceWorker` | Setup wizard UI |
+| `src/routes/policy/+page.svelte` | — | Privacy policy content |
+| `src/routes/login/+page.svelte` | All auth functions: `setupSingleUser`, `unlockSingleUser`, `getSingleUserInfo`, `completeSingleUserSetup`, `completeDeviceVerification`, `pollDeviceVerification`, `fetchRemoteGateConfig`, `linkSingleUserDevice`, `sendDeviceVerification` | Login page UI |
+| `src/routes/confirm/+page.svelte` | Email confirmation via `handleEmailConfirmation()`, `broadcastAuthConfirmed()` | Confirmation page UI |
+| `src/routes/api/config/+server.ts` | Fully managed: `getServerConfig()` | — |
+| `src/routes/api/setup/deploy/+server.ts` | Fully managed: `deployToVercel()` | — |
+| `src/routes/api/setup/validate/+server.ts` | Fully managed: `createValidateHandler()` | — |
+| `src/routes/[...catchall]/+page.ts` | Redirect to `/` | — |
+| `src/routes/(protected)/+layout.ts` | Auth guard via `resolveAuthState()` with login redirect | — (fully managed) |
+| `src/routes/(protected)/+layout.svelte` | — | Protected area chrome |
+| `src/routes/(protected)/profile/+page.svelte` | All profile functions: `changeSingleUserGate`, `updateSingleUserProfile`, `getSingleUserInfo`, `changeSingleUserEmail`, `completeSingleUserEmailChange`, `resetDatabase`, `getTrustedDevices`, `removeTrustedDevice`, `getCurrentDeviceId`, `isDebugMode`, `setDebugMode` | Profile page UI |
+
+**Library (1):** `src/lib/types.ts` with re-exports from stellar-engine + app-specific type stubs
+
+**Git hooks (1):** `.husky/pre-commit` with lint + format + validate
+
+### Parameters
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--name` | Yes | Full app name (e.g., "My Stellar App") |
+| `--short_name` | Yes | Short name for PWA home screen |
+| `--prefix` | Yes | App prefix for localStorage keys, SW, debug utils |
+| `--description` | No | App description (default: "A self-hosted offline-first PWA") |
+
 ## Subpath exports
 
 Import only what you need via subpath exports:
@@ -143,10 +172,11 @@ Import only what you need via subpath exports:
 | `@prabhask5/stellar-engine/stores` | Reactive stores + event subscriptions (`syncStatusStore`, `authState`, `onSyncComplete`, etc.) |
 | `@prabhask5/stellar-engine/types` | All type exports (`Session`, `SyncEngineConfig`, `BatchOperation`, `SingleUserConfig`, etc.) |
 | `@prabhask5/stellar-engine/utils` | Utility functions (`generateId`, `now`, `calculateNewOrder`, `snakeToCamel`, `debug`, etc.) |
-| `@prabhask5/stellar-engine/actions` | Svelte `use:` actions (`remoteChangeAnimation`, `trackEditing`, `triggerLocalAnimation`) |
+| `@prabhask5/stellar-engine/actions` | Svelte `use:` actions (`remoteChangeAnimation`, `trackEditing`, `triggerLocalAnimation`, `truncateTooltip`) |
+| `@prabhask5/stellar-engine/kit` | SvelteKit route helpers, server APIs, load functions, confirmation, auth hydration |
+| `@prabhask5/stellar-engine/components/SyncStatus` | Sync status indicator Svelte component |
+| `@prabhask5/stellar-engine/components/DeferredChangesBanner` | Cross-device conflict banner Svelte component |
 | `@prabhask5/stellar-engine/config` | Runtime config (`initConfig`, `getConfig`, `setConfig`, `getDexieTableFor`) |
-| `@prabhask5/stellar-engine/crdt` | CRDT document lifecycle, realtime sync, awareness/presence, offline cache |
-| `@prabhask5/stellar-engine/email` | Email sending (`sendEmail`, `validateSmtpCredentials`) |
 
 The root export (`@prabhask5/stellar-engine`) re-exports everything for backward compatibility.
 
@@ -280,6 +310,9 @@ Alternatively, you can provide a pre-created Dexie instance via the `db` config
 | `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. |
 | `getUserProfile` / `updateProfile` | Profile read/write via Supabase user metadata. |
+| `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. |
 
 ### Offline auth
 
@@ -395,6 +428,16 @@ When debug mode is enabled, the engine exposes utilities on the `window` object
 | `remoteChangeAnimation` | Svelte `use:` action that animates an element when a remote change arrives. |
 | `trackEditing` | Action that signals the engine a field is being actively edited (suppresses incoming overwrites). |
 | `triggerLocalAnimation` | Programmatically trigger the local-change animation on a node. |
+| `truncateTooltip` | Action that shows a tooltip with full text when content is truncated via CSS overflow. |
+
+### Svelte components
+
+| Export | Description |
+|---|---|
+| `@prabhask5/stellar-engine/components/SyncStatus` | Full Svelte 5 component for animated sync-state indicator with tooltip and PWA refresh. Shows offline/syncing/synced/error/pending states with live indicator. |
+| `@prabhask5/stellar-engine/components/DeferredChangesBanner` | Full Svelte 5 component for cross-device data conflict notification. Shows when another device pushes changes while user is editing. Provides Update/Dismiss/Show Changes actions with diff preview. |
+
+The `UpdatePrompt` component is **not** shipped as a stellar-engine export. Instead, it is generated by `stellar-engine install pwa` at `src/lib/components/UpdatePrompt.svelte` with TODO UI placeholders. The generated component imports `monitorSwLifecycle` and `handleSwUpdate` from `@prabhask5/stellar-engine/kit` for all SW lifecycle logic.
 
 ## Use cases
 

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"}