stellar-drive 1.0.0

package/dist/kit/auth.js

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Auth hydration helper for the root layout component.
+ *
+ * This module bridges the gap between SvelteKit's server-side load data and
+ * the client-side reactive auth store (`authState`). When the root layout
+ * receives auth-related data from a load function, this helper inspects the
+ * `authMode` discriminator and calls the corresponding `authState.set*()`
+ * setter so that every downstream component gets reactive access to the
+ * current authentication state without needing to know the hydration details.
+ *
+ * @module kit/auth
+ *
+ * @example
+ * ```svelte
+ * <!-- +layout.svelte -->
+ * <script lang="ts">
+ *   import { hydrateAuthState } from 'stellar-drive/kit/auth';
+ *   let { data } = $props();
+ *   $effect(() => { hydrateAuthState(data); });
+ * </script>
+ * ```
+ *
+ * @see {@link authState} for the reactive store being hydrated
+ * @see {@link resolveAuthState} in `auth/resolveAuthState.ts` for how auth
+ *      state is determined on the server/load side
+ */
+import { authState } from '../stores/authState.js';
+// =============================================================================
+//  PUBLIC API
+// =============================================================================
+/**
+ * Reads layout load data (`{ authMode, session, offlineProfile }`) and calls
+ * the appropriate `authState.set*()` method to hydrate the client-side
+ * reactive auth store.
+ *
+ * The function acts as a switchboard: it inspects `authMode` and delegates to
+ * the matching setter on the `authState` store. This keeps the root layout
+ * component free of branching logic and ensures a single source of truth for
+ * how layout data maps to reactive state.
+ *
+ * Call this from a Svelte 5 `$effect()` in your root `+layout.svelte` so it
+ * re-runs whenever the layout data changes (e.g. after a login or logout):
+ *
+ * @param layoutData - The auth-related subset of root layout load data.
+ *
+ * @example
+ * ```ts
+ * // In +layout.svelte
+ * $effect(() => { hydrateAuthState(data); });
+ * ```
+ *
+ * @see {@link AuthLayoutData} for the expected shape of `layoutData`
+ * @see {@link authState} for the store methods being invoked
+ */
+export function hydrateAuthState(layoutData) {
+    /* Supabase mode requires both the mode flag AND a valid session object;
+       if the session is null the user has been logged out server-side. */
+    if (layoutData.authMode === 'demo') {
+        authState.setDemoAuth();
+    }
+    else if (layoutData.authMode === 'supabase' && layoutData.session) {
+        authState.setSupabaseAuth(layoutData.session);
+    }
+    else if (layoutData.authMode === 'offline' && layoutData.offlineProfile) {
+        /* Offline mode requires a locally-stored profile to be present;
+           without it we fall through to the unauthenticated state. */
+        authState.setOfflineAuth(layoutData.offlineProfile);
+    }
+    else {
+        /* Catch-all: covers 'none' mode as well as edge cases where the mode
+           flag is set but the corresponding payload is missing. */
+        authState.setNoAuth();
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/kit/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/kit/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAqCnD,gFAAgF;AAChF,cAAc;AACd,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAA0B;IACzD;0EACsE;IACtE,IAAI,UAAU,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;QACnC,SAAS,CAAC,WAAW,EAAE,CAAC;IAC1B,CAAC;SAAM,IAAI,UAAU,CAAC,QAAQ,KAAK,UAAU,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC;QACpE,SAAS,CAAC,eAAe,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC;SAAM,IAAI,UAAU,CAAC,QAAQ,KAAK,SAAS,IAAI,UAAU,CAAC,cAAc,EAAE,CAAC;QAC1E;sEAC8D;QAC9D,SAAS,CAAC,cAAc,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;IACtD,CAAC;SAAM,CAAC;QACN;mEAC2D;QAC3D,SAAS,CAAC,SAAS,EAAE,CAAC;IACxB,CAAC;AACH,CAAC"}

package/dist/kit/confirm.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview Email confirmation helpers for the `/confirm` route.
+ *
+ * This module extracts the OTP verification, device trust, error translation,
+ * and cross-tab broadcast logic so that the scaffolded confirmation page can
+ * focus purely on UI rendering. It handles the full lifecycle of an email
+ * confirmation link click:
+ *
+ *   1. Verify the OTP token hash with Supabase
+ *   2. Trust the originating device (for device-verification flows)
+ *   3. Translate raw Supabase errors into user-friendly messages
+ *   4. Broadcast the confirmation to other open tabs via BroadcastChannel
+ *   5. Attempt to auto-close the confirmation tab
+ *
+ * @module kit/confirm
+ *
+ * @example
+ * ```ts
+ * // In /confirm/+page.svelte onMount
+ * const result = await handleEmailConfirmation(tokenHash, type);
+ * if (result.success) {
+ *   await broadcastAuthConfirmed('auth-channel', type);
+ * }
+ * ```
+ *
+ * @see {@link verifyOtp} in `supabase/auth.ts` for the underlying OTP call
+ * @see {@link trustPendingDevice} in `auth/deviceVerification.ts` for device trust logic
+ */
+/**
+ * Result of an email confirmation attempt.
+ *
+ * Provides a simple success/failure discriminator with an optional
+ * user-friendly error message when the confirmation fails.
+ */
+export interface ConfirmResult {
+    /** Whether the OTP verification completed successfully. */
+    success: boolean;
+    /**
+     * A user-facing error message explaining why confirmation failed.
+     * Only present when `success` is `false`.
+     */
+    error?: string;
+}
+/**
+ * Handles the full email confirmation flow: verifies the OTP token hash,
+ * optionally trusts the pending device, and translates Supabase error
+ * messages into user-friendly strings.
+ *
+ * The function normalizes the `type` parameter before passing it to Supabase
+ * (e.g. `'magiclink'` maps to `'email'` for OTP verification purposes) and
+ * applies a tiered error classification to produce contextual error messages.
+ *
+ * @param tokenHash - The `token_hash` extracted from the confirmation URL
+ *                    query parameters (provided by Supabase in the email link).
+ * @param type      - The verification type from Supabase, indicating what kind
+ *                    of email action triggered the confirmation. One of:
+ *                    - `'signup'` — new account registration
+ *                    - `'email'` — email change or device verification
+ *                    - `'email_change'` — explicit email address change
+ *                    - `'magiclink'` — passwordless login link
+ *
+ * @returns A promise resolving to `{ success: true }` on successful
+ *          verification, or `{ success: false, error: string }` on failure
+ *          with a translated error message.
+ *
+ * @example
+ * ```ts
+ * const result = await handleEmailConfirmation(tokenHash, 'signup');
+ * if (!result.success) {
+ *   showError(result.error);
+ * }
+ * ```
+ *
+ * @see {@link ConfirmResult} for the return type shape
+ * @see {@link verifyOtp} for the underlying Supabase OTP verification
+ */
+export declare function handleEmailConfirmation(tokenHash: string, type: 'signup' | 'email' | 'email_change' | 'magiclink'): Promise<ConfirmResult>;
+/**
+ * Broadcasts an auth confirmation event via `BroadcastChannel` so other
+ * open tabs (e.g. the login page that initiated the email flow) can detect
+ * the completed authentication and update their UI accordingly.
+ *
+ * After broadcasting, the function waits briefly for the receiving tab to
+ * process the message, then attempts to auto-close this confirmation tab.
+ * If the browser blocks `window.close()` (common for tabs not opened via
+ * `window.open()`), the function returns `'can_close'` so the UI can show
+ * a "you may close this tab" message instead.
+ *
+ * @param channelName - The `BroadcastChannel` name. Must match the channel
+ *                      name used by the login page listener.
+ * @param type        - The verification type to include in the broadcast
+ *                      message payload, so the receiver knows which flow
+ *                      completed.
+ *
+ * @returns A promise resolving to one of:
+ *   - `'closed'`       — tab was successfully closed (caller won't see this)
+ *   - `'can_close'`    — broadcast sent but tab could not auto-close
+ *   - `'no_broadcast'` — BroadcastChannel API not available (SSR or old browser)
+ *
+ * @example
+ * ```ts
+ * const status = await broadcastAuthConfirmed('stellar-auth', 'signup');
+ * if (status === 'can_close') {
+ *   showMessage('You can close this tab.');
+ * }
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel}
+ */
+export declare function broadcastAuthConfirmed(channelName: string, type: string): Promise<'closed' | 'can_close' | 'no_broadcast'>;
+//# sourceMappingURL=confirm.d.ts.map

package/dist/kit/confirm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm.d.ts","sourceRoot":"","sources":["../../src/kit/confirm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AASH;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,cAAc,GAAG,WAAW,GACtD,OAAO,CAAC,aAAa,CAAC,CA4CxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,QAAQ,GAAG,WAAW,GAAG,cAAc,CAAC,CA+BlD"}

package/dist/kit/confirm.js

@@ -0,0 +1,169 @@
+/**
+ * @fileoverview Email confirmation helpers for the `/confirm` route.
+ *
+ * This module extracts the OTP verification, device trust, error translation,
+ * and cross-tab broadcast logic so that the scaffolded confirmation page can
+ * focus purely on UI rendering. It handles the full lifecycle of an email
+ * confirmation link click:
+ *
+ *   1. Verify the OTP token hash with Supabase
+ *   2. Trust the originating device (for device-verification flows)
+ *   3. Translate raw Supabase errors into user-friendly messages
+ *   4. Broadcast the confirmation to other open tabs via BroadcastChannel
+ *   5. Attempt to auto-close the confirmation tab
+ *
+ * @module kit/confirm
+ *
+ * @example
+ * ```ts
+ * // In /confirm/+page.svelte onMount
+ * const result = await handleEmailConfirmation(tokenHash, type);
+ * if (result.success) {
+ *   await broadcastAuthConfirmed('auth-channel', type);
+ * }
+ * ```
+ *
+ * @see {@link verifyOtp} in `supabase/auth.ts` for the underlying OTP call
+ * @see {@link trustPendingDevice} in `auth/deviceVerification.ts` for device trust logic
+ */
+import { verifyOtp } from '../supabase/auth.js';
+import { trustPendingDevice } from '../auth/deviceVerification.js';
+// =============================================================================
+//  PUBLIC API
+// =============================================================================
+/**
+ * Handles the full email confirmation flow: verifies the OTP token hash,
+ * optionally trusts the pending device, and translates Supabase error
+ * messages into user-friendly strings.
+ *
+ * The function normalizes the `type` parameter before passing it to Supabase
+ * (e.g. `'magiclink'` maps to `'email'` for OTP verification purposes) and
+ * applies a tiered error classification to produce contextual error messages.
+ *
+ * @param tokenHash - The `token_hash` extracted from the confirmation URL
+ *                    query parameters (provided by Supabase in the email link).
+ * @param type      - The verification type from Supabase, indicating what kind
+ *                    of email action triggered the confirmation. One of:
+ *                    - `'signup'` — new account registration
+ *                    - `'email'` — email change or device verification
+ *                    - `'email_change'` — explicit email address change
+ *                    - `'magiclink'` — passwordless login link
+ *
+ * @returns A promise resolving to `{ success: true }` on successful
+ *          verification, or `{ success: false, error: string }` on failure
+ *          with a translated error message.
+ *
+ * @example
+ * ```ts
+ * const result = await handleEmailConfirmation(tokenHash, 'signup');
+ * if (!result.success) {
+ *   showError(result.error);
+ * }
+ * ```
+ *
+ * @see {@link ConfirmResult} for the return type shape
+ * @see {@link verifyOtp} for the underlying Supabase OTP verification
+ */
+export async function handleEmailConfirmation(tokenHash, type) {
+    try {
+        /* Supabase's verifyOtp does not accept 'magiclink' as a type;
+           it expects 'email' for both magic link and email verification flows. */
+        const otpType = type === 'magiclink' ? 'email' : type;
+        const { error } = await verifyOtp(tokenHash, otpType);
+        /* For device-verification OTPs (email or magiclink), trust the device
+           that initiated the confirmation so it won't be challenged again. */
+        if (!error && (type === 'email' || type === 'magiclink')) {
+            await trustPendingDevice();
+        }
+        if (error) {
+            /* Tiered error classification: check for common Supabase error patterns
+               and translate them to actionable user-facing messages rather than
+               exposing raw API error strings. */
+            const errorLower = error.toLowerCase();
+            if (errorLower.includes('already') ||
+                errorLower.includes('confirmed') ||
+                errorLower.includes('used')) {
+                return {
+                    success: false,
+                    error: 'This email has already been confirmed. You can sign in to your account.'
+                };
+            }
+            else if (errorLower.includes('expired') || errorLower.includes('invalid')) {
+                return {
+                    success: false,
+                    error: 'This confirmation link has expired. Please request a new one from the login page.'
+                };
+            }
+            /* Unrecognized error pattern — pass through the raw message as a
+               last resort; this should be rare in production. */
+            return { success: false, error };
+        }
+        return { success: true };
+    }
+    catch {
+        /* Catch network failures, unexpected exceptions, etc. The user sees
+           a generic message rather than a stack trace. */
+        return { success: false, error: 'An unexpected error occurred. Please try again.' };
+    }
+}
+/**
+ * Broadcasts an auth confirmation event via `BroadcastChannel` so other
+ * open tabs (e.g. the login page that initiated the email flow) can detect
+ * the completed authentication and update their UI accordingly.
+ *
+ * After broadcasting, the function waits briefly for the receiving tab to
+ * process the message, then attempts to auto-close this confirmation tab.
+ * If the browser blocks `window.close()` (common for tabs not opened via
+ * `window.open()`), the function returns `'can_close'` so the UI can show
+ * a "you may close this tab" message instead.
+ *
+ * @param channelName - The `BroadcastChannel` name. Must match the channel
+ *                      name used by the login page listener.
+ * @param type        - The verification type to include in the broadcast
+ *                      message payload, so the receiver knows which flow
+ *                      completed.
+ *
+ * @returns A promise resolving to one of:
+ *   - `'closed'`       — tab was successfully closed (caller won't see this)
+ *   - `'can_close'`    — broadcast sent but tab could not auto-close
+ *   - `'no_broadcast'` — BroadcastChannel API not available (SSR or old browser)
+ *
+ * @example
+ * ```ts
+ * const status = await broadcastAuthConfirmed('stellar-auth', 'signup');
+ * if (status === 'can_close') {
+ *   showMessage('You can close this tab.');
+ * }
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel}
+ */
+export async function broadcastAuthConfirmed(channelName, type) {
+    /* Guard against SSR and browsers lacking BroadcastChannel support
+       (notably some older mobile browsers). */
+    if (typeof window === 'undefined' || !('BroadcastChannel' in window)) {
+        return 'no_broadcast';
+    }
+    const channel = new BroadcastChannel(channelName);
+    channel.postMessage({
+        type: 'AUTH_CONFIRMED',
+        verificationType: type
+    });
+    /* Give the original tab time to process the message before closing
+       the channel — 500ms is sufficient for the receiver's event loop
+       to fire the handler and update its state. */
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    channel.close();
+    /* Attempt to close this confirmation tab — browsers generally only
+       allow window.close() for tabs opened programmatically via
+       window.open(), so this may silently fail. */
+    try {
+        window.close();
+    }
+    catch {
+        /* Browser policy may block window.close() — expected behavior */
+    }
+    /* If execution reaches here, the tab is still open (close was blocked) */
+    return 'can_close';
+}
+//# sourceMappingURL=confirm.js.map

package/dist/kit/confirm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm.js","sourceRoot":"","sources":["../../src/kit/confirm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAuBnE,gFAAgF;AAChF,cAAc;AACd,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,SAAiB,EACjB,IAAuD;IAEvD,IAAI,CAAC;QACH;kFAC0E;QAC1E,MAAM,OAAO,GAAG,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;QACtD,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,SAAS,CAAC,SAAS,EAAE,OAA8C,CAAC,CAAC;QAE7F;8EACsE;QACtE,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,WAAW,CAAC,EAAE,CAAC;YACzD,MAAM,kBAAkB,EAAE,CAAC;QAC7B,CAAC;QAED,IAAI,KAAK,EAAE,CAAC;YACV;;iDAEqC;YACrC,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;YACvC,IACE,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC;gBAC9B,UAAU,CAAC,QAAQ,CAAC,WAAW,CAAC;gBAChC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,EAC3B,CAAC;gBACD,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,yEAAyE;iBACjF,CAAC;YACJ,CAAC;iBAAM,IAAI,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC5E,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,mFAAmF;iBAC3F,CAAC;YACJ,CAAC;YACD;iEACqD;YACrD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QACnC,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP;0DACkD;QAClD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,iDAAiD,EAAE,CAAC;IACtF,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,WAAmB,EACnB,IAAY;IAEZ;+CAC2C;IAC3C,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,CAAC,CAAC,kBAAkB,IAAI,MAAM,CAAC,EAAE,CAAC;QACrE,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC,WAAW,CAAC,CAAC;IAElD,OAAO,CAAC,WAAW,CAAC;QAClB,IAAI,EAAE,gBAAgB;QACtB,gBAAgB,EAAE,IAAI;KACvB,CAAC,CAAC;IAEH;;mDAE+C;IAC/C,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;IACzD,OAAO,CAAC,KAAK,EAAE,CAAC;IAEhB;;mDAE+C;IAC/C,IAAI,CAAC;QACH,MAAM,CAAC,KAAK,EAAE,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,iEAAiE;IACnE,CAAC;IAED,0EAA0E;IAC1E,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/kit/loads.d.ts

@@ -0,0 +1,187 @@
+/**
+ * @fileoverview SvelteKit load function helpers.
+ *
+ * This module extracts orchestration logic from layout and page load functions
+ * so that scaffolded routes can be thin wrappers around these helpers. Each
+ * exported function encapsulates a specific load concern:
+ *
+ *   - `resolveRootLayout`      — full app initialization sequence (config,
+ *                                 auth, sync engine startup)
+ *   - `resolveProtectedLayout` — auth guard for protected route groups
+ *   - `resolveSetupAccess`     — access control for the `/setup` wizard
+ *
+ * By centralizing this logic in the engine, consuming apps avoid duplicating
+ * the initialization ordering and redirect logic across their route tree.
+ *
+ * @module kit/loads
+ *
+ * @example
+ * ```ts
+ * // In +layout.ts (root)
+ * import { resolveRootLayout } from 'stellar-drive/kit/loads';
+ * export async function load({ url }) {
+ *   return resolveRootLayout(url);
+ * }
+ * ```
+ *
+ * @see {@link initConfig} for runtime configuration bootstrap
+ * @see {@link resolveAuthState} for auth mode determination
+ * @see {@link startSyncEngine} for offline-first sync initialization
+ */
+import type { AuthStateResult } from '../auth/resolveAuthState.js';
+/**
+ * Data returned by `resolveRootLayout`.
+ *
+ * Extends the base auth state with an optional `singleUserSetUp` flag
+ * indicating whether the app has completed initial configuration.
+ */
+export interface RootLayoutData extends AuthStateResult {
+    /**
+     * Indicates whether the single-user setup wizard has been completed.
+     * When `false` and no config exists, the app should redirect to `/setup`.
+     */
+    singleUserSetUp?: boolean;
+}
+/**
+ * Data returned by `resolveProtectedLayout`.
+ *
+ * A narrowed subset of auth state fields needed by protected route groups
+ * to render authenticated content.
+ */
+export interface ProtectedLayoutData {
+    /** The Supabase session, or `null` if using offline/no auth. */
+    session: AuthStateResult['session'];
+    /** The active authentication mode discriminator. */
+    authMode: AuthStateResult['authMode'];
+    /** The offline profile credentials, if in offline mode. */
+    offlineProfile: AuthStateResult['offlineProfile'];
+}
+/**
+ * Data returned by `resolveSetupAccess`.
+ *
+ * Tells the setup page whether this is a first-time configuration
+ * (public access) or a reconfiguration (authenticated users only).
+ */
+export interface SetupAccessData {
+    /**
+     * `true` when no configuration exists yet — the setup page should
+     * render the full first-time wizard without requiring authentication.
+     */
+    isFirstSetup: boolean;
+}
+/**
+ * Orchestrates the root layout load sequence, which is the critical
+ * initialization path that runs on every page load:
+ *
+ *   1. Calls the app's `initEngine` function (for database schema setup)
+ *   2. Runs `initConfig()` — loads runtime config from storage; if no
+ *      config exists and the user is not already on `/setup`, returns a
+ *      blank state so the layout can redirect to the setup wizard
+ *   3. Resolves auth state — determines whether the user is authenticated
+ *      via Supabase, offline credentials, or not at all
+ *   4. Starts the sync engine if the user is authenticated, enabling
+ *      offline-first data synchronization
+ *
+ * @param url          - The current page URL object. Only `pathname` is
+ *                       inspected, to detect whether the user is already
+ *                       on the `/setup` page.
+ * @param _initEngineFn - (Optional) The app's `initEngine()` call, executed
+ *                        before config init. Typically already called at
+ *                        module scope in the browser; this parameter exists
+ *                        for explicit invocation in SSR contexts.
+ *
+ * @returns Layout data containing session, auth mode, offline profile,
+ *          and setup status. The consuming layout uses these to hydrate
+ *          the auth store and conditionally render the app shell.
+ *
+ * @example
+ * ```ts
+ * // +layout.ts
+ * export async function load({ url }) {
+ *   return resolveRootLayout(url);
+ * }
+ * ```
+ *
+ * @see {@link RootLayoutData} for the return type shape
+ * @see {@link initConfig} for config bootstrapping details
+ * @see {@link resolveAuthState} for auth resolution logic
+ */
+export declare function resolveRootLayout(url: {
+    pathname: string;
+}, _initEngineFn?: () => void): Promise<RootLayoutData>;
+/**
+ * Auth guard for protected routes. Resolves auth state and, if the user
+ * is unauthenticated, computes a redirect URL to the login page with a
+ * `redirect` query parameter so the user can be sent back after login.
+ *
+ * The caller is responsible for performing the actual redirect (typically
+ * via SvelteKit's `throw redirect(302, redirectUrl)`), since this helper
+ * is framework-agnostic in its return value.
+ *
+ * @param url - The current page URL object with `pathname` and `search`
+ *              properties, used to construct the post-login return URL.
+ *
+ * @returns An object containing:
+ *   - `data` — the auth state payload for the layout
+ *   - `redirectUrl` — a login URL string if unauthenticated, or `null`
+ *     if the user is authenticated and should proceed normally.
+ *     When non-null, the caller should `throw redirect(302, redirectUrl)`.
+ *
+ * @example
+ * ```ts
+ * // /(protected)/+layout.ts
+ * import { redirect } from '@sveltejs/kit';
+ * import { resolveProtectedLayout } from 'stellar-drive/kit/loads';
+ *
+ * export async function load({ url }) {
+ *   const { data, redirectUrl } = await resolveProtectedLayout(url);
+ *   if (redirectUrl) throw redirect(302, redirectUrl);
+ *   return data;
+ * }
+ * ```
+ *
+ * @see {@link ProtectedLayoutData} for the return data shape
+ * @see {@link resolveAuthState} for the underlying auth resolution
+ */
+export declare function resolveProtectedLayout(url: {
+    pathname: string;
+    search: string;
+}): Promise<{
+    data: ProtectedLayoutData;
+    redirectUrl: string | null;
+}>;
+/**
+ * Setup page guard implementing a two-tier access model:
+ *
+ *   - **Unconfigured app** (first-time setup): public access, no auth required.
+ *     Returns `{ isFirstSetup: true }`.
+ *   - **Configured app** (reconfiguration): any authenticated user may access.
+ *     Unauthenticated users are redirected to `/login`.
+ *
+ * @returns An object containing:
+ *   - `data` — setup access info (`{ isFirstSetup }`)
+ *   - `redirectUrl` — a redirect path if the user lacks access, or `null`
+ *     if access is granted. When non-null, the caller should
+ *     `throw redirect(302, redirectUrl)`.
+ *
+ * @example
+ * ```ts
+ * // /setup/+page.ts
+ * import { redirect } from '@sveltejs/kit';
+ * import { resolveSetupAccess } from 'stellar-drive/kit/loads';
+ *
+ * export async function load() {
+ *   const { data, redirectUrl } = await resolveSetupAccess();
+ *   if (redirectUrl) throw redirect(302, redirectUrl);
+ *   return data;
+ * }
+ * ```
+ *
+ * @see {@link SetupAccessData} for the return data shape
+ * @see {@link getConfig} for checking whether config exists
+ */
+export declare function resolveSetupAccess(): Promise<{
+    data: SetupAccessData;
+    redirectUrl: string | null;
+}>;
+//# sourceMappingURL=loads.d.ts.map

package/dist/kit/loads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loads.d.ts","sourceRoot":"","sources":["../../src/kit/loads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAMnE;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAEpC,oDAAoD;IACpD,QAAQ,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC;IAEtC,2DAA2D;IAC3D,cAAc,EAAE,eAAe,CAAC,gBAAgB,CAAC,CAAC;CACnD;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;CACvB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,EACzB,aAAa,CAAC,EAAE,MAAM,IAAI,GACzB,OAAO,CAAC,cAAc,CAAC,CAmCzB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,sBAAsB,CAAC,GAAG,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAgBrE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC;IAClD,IAAI,EAAE,eAAe,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC,CAqBD"}