import { StoreDescriptor, StoreFactory, StoreLocator, NoydbStore } from '@noy-db/hub/to';

/**
 * **@noy-db/to-browser-local** — `localStorage`-backed NOYDB store.
 *
 * All data is stored under `localStorage` with keys of the form
 * `{prefix}:{vault}:{collection}:{id}`. CAS checks are synchronous and
 * inherently atomic within a single JS thread.
 *
 * ## When to use
 *
 * Use `@noy-db/to-browser-idb` for most browser applications — it supports
 * larger storage quotas and true atomic transactions. Prefer this store only
 * when IndexedDB is unavailable (rare) or when you need storage that survives
 * across `sessionStorage` clears but is inspectable without DevTools.
 *
 * ## Obfuscation mode
 *
 * Setting `obfuscate: true` replaces each key component with an FNV-1a hash
 * and XOR-encodes metadata (vault name, collection name, record ID, `_by`
 * attribution) so that the logical structure of the data is not visible to
 * browser extensions or DevTools. This is **not** encryption — the envelope
 * `_data` field is always AES-GCM ciphertext regardless of this setting.
 *
 * ## Capabilities
 *
 * | Capability | Value |
 * |---|---|
 * | `casAtomic` | `false` — single-tab only; cross-tab writes share storage with no serialization |
 * | `serverWriteTime` | `true` — browser clock; same-tab only |
 * | `listPage` | ✓ — cursor-based pagination |
 * | `ping` | ✓ — round-trips a sentinel key |
 *
 * @packageDocumentation
 */

/**
 * Options for `toBrowserLocal()`.
 *
 * All NOYDB data is stored in `localStorage` under `{prefix}:{vault}:{collection}:{id}`.
 * Enable `obfuscate` to replace each path component with an FNV-1a hash and
 * XOR-encode metadata so vault/collection/record names are not visible to
 * browser extensions or DevTools inspecting `localStorage`.
 */
interface BrowserLocalOptions {
    /** Storage key prefix. Default: 'noydb'. */
    prefix?: string;
    /** Obfuscate storage keys so collection/record names are not readable. Default: false. */
    obfuscate?: boolean;
    /** Clock uncertainty bound (ms). Default: 0. */
    clockUncertaintyMs?: number;
}
/**
 * Create a localStorage-backed store adapter.
 *
 * Key scheme (normal):    `{prefix}:{vault}:{collection}:{id}`
 * Key scheme (obfuscated): `{prefix}:{hash}:{hash}:{hash}`
 *
 * StoreCapabilities:
 *   casAtomic: false — single-tab: synchronous and inherently atomic; cross-tab: no serialization
 *   auth: { kind: 'browser-origin', flow: 'implicit', required: false }
 */
declare function toBrowserLocal(options?: BrowserLocalOptions): NoydbStore;
/** Serializable location of a localStorage store: just the key prefix. */
interface BrowserLocalAddress {
    readonly prefix?: string;
}
/** Serializable tuning carried on the descriptor (never credentials). */
interface BrowserLocalDescriptorOptions {
    readonly obfuscate?: boolean;
    readonly clockUncertaintyMs?: number;
}
/**
 * Builds the `StoreDescriptor` form of a `toBrowserLocal()` store:
 * `kind: 'browser-local'`, `class: 'browser'`. Credentialless by
 * construction — localStorage needs no credentials at all, so this store
 * ignores both `binding` and `credentials` at resolve time.
 */
declare function browserLocalStoreDescriptor(address?: BrowserLocalAddress, options?: BrowserLocalDescriptorOptions): StoreDescriptor;
/**
 * `StoreFactory` for `to-browser-local`: reconstructs the same store
 * `toBrowserLocal()` builds, from a descriptor produced by
 * {@link browserLocalStoreDescriptor}.
 */
declare const browserLocalStoreFactory: StoreFactory;
/** Registers {@link browserLocalStoreFactory} under the `'browser-local'` kind on `locator`. */
declare function registerBrowserLocalStore(locator: StoreLocator): void;

export { type BrowserLocalAddress, type BrowserLocalDescriptorOptions, type BrowserLocalOptions, browserLocalStoreDescriptor, browserLocalStoreFactory, registerBrowserLocalStore, toBrowserLocal };