/**
 * tina4-js/storage — Persistent signals.
 *
 * Wrap a signal with persist() to read its initial value from localStorage
 * (or sessionStorage) and write every change back. The value survives a
 * page refresh. Opt-in per signal. Zero dependencies.
 *
 * SAFE FOR: theme, language, sidebar state, last-used filters, onboarding
 *           flags, draft text the user expects back, guest cart contents.
 *
 * NEVER STORE: auth tokens, JWTs, session IDs, API keys, passwords, personal
 *              data, payment details, permission flags, secrets, OTP seeds,
 *              or any server-of-record state. localStorage is XSS-readable.
 *              See STORAGE.md for the full dangers list.
 */
import { type Signal } from '../core/signal';
export interface PersistSerializer<T> {
    /** Parse a stored string back into a value. */
    read(raw: string): T;
    /** Serialize a value into a string that storage can hold. */
    write(value: T): string;
}
export interface PersistOptions<T> {
    /** Storage key. Required. */
    key: string;
    /** 'local' (default) survives a refresh; 'session' lives until the tab closes. */
    storage?: 'local' | 'session';
    /** JSON by default. Provide for Date, Map, Set, or any non-JSON shape. */
    serializer?: PersistSerializer<T>;
    /** Stored-shape version. Defaults to 1. */
    version?: number;
    /** Convert an older stored value into the current shape. */
    migrate?: (oldValue: unknown, oldVersion: number | undefined) => T;
    /** Subscribe to the storage event so other tabs see writes. Opt-in. */
    syncTabs?: boolean;
    /**
     * Silence the credential-shape warning. Use only when you are certain
     * the key or value is a coincidence (e.g. tokenColor for a UI palette).
     */
    silenceCredentialWarning?: boolean;
}
export interface PersistedSignal<T> extends Signal<T> {
    /** Remove the key from storage. The signal keeps its current in-memory value. */
    clear(): void;
    /** Stop watching storage events and stop the write effect. */
    dispose(): void;
}
/** @internal Reset the warning cache. Tests only. */
export declare function _resetWarnedKeys(): void;
/**
 * Wrap a signal so its value is read from storage on creation and written
 * back on every change. Survives a page refresh.
 *
 * @param source  - The signal to persist. Its initial value is overwritten
 *                  by whatever is in storage, if anything.
 * @param options - Persistence options. `key` is required.
 *
 * @example
 *   const theme = persist(signal('light'), { key: 'theme' });
 *   theme.value = 'dark';   // survives a refresh
 */
export declare function persist<T>(source: Signal<T>, options: PersistOptions<T>): PersistedSignal<T>;
/**
 * Remove a list of persisted keys at once. Wire this to your logout handler
 * so persisted state does not leak to the next user on the device.
 *
 * @example
 *   function logout() {
 *     api.post('/auth/logout');
 *     clearPersistedKeys(['cart', 'lastFilter', 'draftReply']);
 *     window.location.reload();
 *   }
 */
export declare function clearPersistedKeys(keys: string[], kind?: 'local' | 'session'): void;
//# sourceMappingURL=persist.d.ts.map