/**
 * @deijose/nix-ionic / page-state.ts
 *
 * Opt-in page-state persistence protocol. Allows pages to save and restore
 * serializable state across navigation, cache eviction, and app reloads.
 *
 * Key design rules:
 *   - **Only serializable data** — JSON.stringify is used; DOM nodes, functions,
 *     symbols, class instances with methods are rejected.
 *   - **Never persist DOM/view instances** — the protocol validates values
 *     before storage and throws on non-serializable content.
 *   - **Opt-in** — pages must explicitly call `save()` to persist state.
 *   - **Per cache key** — state is keyed by route path + params + query,
 *     matching the IonRouterOutlet cache key logic.
 *   - **Storage choice** — `sessionStorage` (default, cleared on tab close)
 *     or `localStorage` (persists across sessions).
 *
 * @example Basic usage in a page component
 * ```ts
 * import { signal, html } from "@deijose/nix-js";
 * import { createPageState, IonPage } from "@deijose/nix-ionic";
 *
 * class SearchPage extends IonPage {
 *   private query = signal("");
 *   private results = signal<string[]>([]);
 *   private pageState = createPageState("search", {
 *     // Declare which signals are persistable
 *     query: this.query,
 *     results: this.results,
 *   });
 *
 *   override onMount() {
 *     // Restore saved state on mount
 *     this.pageState.restore();
 *   }
 *
 *   override onUnmount() {
 *     // Save state before leaving
 *     this.pageState.save();
 *   }
 *
 *   override render() {
 *     return html`
 *       <ion-content>
 *         <ion-searchbar value=${() => this.query.value} @input=${(e: any) => {
 *           this.query.value = e.target.value;
 *           this.pageState.save(); // save on change
 *         }}></ion-searchbar>
 *         <ion-list>
 *           ${() => this.results.value.map(r => html`<ion-item>${r}</ion-item>`)}
 *         </ion-list>
 *       </ion-content>
 *     `;
 *   }
 * }
 * ```
 *
 * @example With localStorage (persists across app restarts)
 * ```ts
 * const pageState = createPageState("cart", {
 *   items: cartItems,
 *   total: cartTotal,
 * }, { storage: "local" });
 * ```
 */
/** Storage backend selection. */
export type StorageBackend = "session" | "local";
/** Options for page-state persistence. */
export interface PageStateOptions {
    /**
     * Storage backend: `"session"` (sessionStorage, cleared on tab close)
     * or `"local"` (localStorage, persists across sessions).
     * @default "session"
     */
    storage?: StorageBackend;
    /**
     * Namespace prefix for storage keys. Defaults to "nix-ionic".
     * Useful for multi-app scenarios on the same origin.
     */
    namespace?: string;
    /**
     * Additional key suffix (e.g. user ID) to isolate state between users.
     */
    keySuffix?: string;
}
/**
 * A map of signal names to signals. Each signal's value must be serializable.
 */
export type SignalMap = Record<string, {
    value: unknown;
}>;
/**
 * Page-state persistence controller. Created per page instance.
 */
export interface PageState {
    /**
     * Save the current state of all declared signals to storage.
     * Only serializable values are stored; non-serializable values are
     * silently skipped (with a console.warn in dev).
     */
    save(): void;
    /**
     * Restore saved state from storage into the declared signals.
     * Returns true if state was found and restored, false otherwise.
     */
    restore(): boolean;
    /**
     * Clear saved state for this page's key.
     */
    clear(): void;
    /**
     * Get the storage key that would be used (for debugging).
     */
    readonly key: string;
}
/**
 * Check if a value is serializable (can survive JSON.stringify + parse).
 * Returns true for: primitives, plain arrays, plain objects.
 * Returns false for: functions, symbols, DOM nodes, class instances,
 * undefined, circular references.
 */
declare function isSerializable(value: unknown): boolean;
/**
 * Create a page-state persistence controller.
 *
 * @param pageId Unique identifier for the page (e.g. route path).
 * @param signals Map of signal names to signals whose values should be persisted.
 * @param options Persistence options.
 *
 * @example
 * ```ts
 * const state = createPageState("search", {
 *   query: searchQuery,
 *   filters: filterSignal,
 * }, { storage: "local" });
 *
 * // On page mount:
 * state.restore();
 *
 * // On page leave or data change:
 * state.save();
 * ```
 */
export declare function createPageState(pageId: string, signals: SignalMap, options?: PageStateOptions): PageState;
/**
 * Clear all nix-ionic page-state entries from a storage backend.
 * Useful for logout flows.
 *
 * @example
 * ```ts
 * import { clearAllPageState } from "@deijose/nix-ionic";
 *
 * function logout() {
 *   clearAllPageState(); // sessionStorage
 *   clearAllPageState("local"); // localStorage
 * }
 * ```
 */
export declare function clearAllPageState(backend?: StorageBackend, namespace?: string): void;
export { isSerializable };