/**
 * @module context-mode-service
 *
 * Implements the WebContextModeService for @ibgib/web-gib.
 * Manages the active runtime ModeExecutionContext and handles discrete, fail-fast
 * transitions between:
 * - Mode 1: Ephemeral Playground Sandbox ('playground')
 * - Mode 2: Locally Installed Sovereign Workspace ('local')
 * - Mode 3: Remote Server Browsing ('remote')
 */
import { ContextMode, ModeExecutionContext, ContextModeInitOptions } from "@ibgib/core-gib/dist/context/context-mode-types.mjs";
import { MetaspaceService } from "@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs";
import { KeystoneIbGib_V1 } from "@ibgib/core-gib/dist/keystone/keystone-types.mjs";
/**
 * Device-scoped identity info (resolved by the identity header).
 */
export interface PersistentIdentityInfo {
    domainIdentity: KeystoneIbGib_V1;
    syncDelegateIdentity?: KeystoneIbGib_V1;
    tjpAddr: string;
    username?: string;
    siteUsername?: string;
    aggregateDetails?: {
        username: string;
        description: string;
        isPrimary: boolean;
    };
    authenticated: boolean;
    resolved: boolean;
}
export declare class WebContextModeService {
    private _activeContext;
    private _playgroundContext;
    private _localUserContext;
    private _persistentLocalMetaspace;
    private _persistentIdentity;
    /**
     * Registers (or clears, with `undefined`) the device-scoped identity.
     * Driven by the identity header. Identity is mode-agnostic: it pairs with
     * the persistent metaspace, not with the active execution context.
     */
    registerPersistentIdentity(identity: PersistentIdentityInfo | undefined): void;
    /**
     * Returns the device-scoped identity, or `undefined` if the user is not
     * authenticated on this device (a valid state, not an error).
     */
    getPersistentIdentity(): PersistentIdentityInfo | undefined;
    /**
     * Registers the persistent Metaspace created during app bootstrap (e.g. Metaspace_Webspace)
     * to ensure Mode 1 in-memory sandbox never clobbers Mode 2 local storage.
     */
    registerPersistentMetaspace(metaspace: MetaspaceService): void;
    /**
     * Returns the persistent device Metaspace (e.g. Metaspace_Webspace) registered
     * during app bootstrap, independent of the currently active context mode.
     *
     * Device-scoped concerns (e.g. Keystone identities, the identity header) MUST use
     * this rather than the active metaspace, since Mode 1 swaps in an ephemeral
     * in-memory metaspace.
     *
     * @throws if bootstrap has not yet registered the persistent metaspace (fail fast).
     */
    getPersistentMetaspace(): MetaspaceService;
    /**
     * Returns the persistent device Metaspace, waiting if bootstrap registration
     * is still completing.
     */
    getPersistentMetaspace_waitIfNeeded({ delayIntervalMs, maxWaitMs, }?: {
        delayIntervalMs?: number | undefined;
        maxWaitMs?: number | undefined;
    }): Promise<MetaspaceService>;
    /**
     * Returns the ephemeral in-memory @playground metaspace regardless of the
     * currently active mode.
     *
     * @throws if the playground context has not been initialized (fail fast).
     */
    getPlaygroundMetaspace(): MetaspaceService;
    /**
     * Gets the currently active execution context.
     * Fails fast if no mode has been activated yet.
     */
    get current(): ModeExecutionContext;
    /**
     * Returns the active mode ('playground' | 'local' | 'remote') or undefined if uninitialized.
     */
    get activeMode(): ContextMode | undefined;
    /**
     * Checks if an execution context has already been activated.
     */
    get hasActiveContext(): boolean;
    /**
     * Helper to retrieve the active Metaspace instance.
     * Used by getGlobalMetaspace_waitIfNeeded() for transparent delegation.
     */
    getActiveMetaspace(): Promise<MetaspaceService>;
    /**
     * Activates a specific context mode, booting or restoring its backing space and identity context.
     */
    activateMode(mode: ContextMode, opts?: ContextModeInitOptions): Promise<ModeExecutionContext>;
    /**
     * Initializes or restores Mode 1: Ephemeral Playground Sandbox.
     * Backed 100% by in-memory InnerSpace_V1 with an ephemeral sovereign keystone.
     * Invariant: Never contacts server, never writes to persistent disk.
     */
    private initMode1PlaygroundContext;
    /**
     * Initializes or restores Mode 2: Locally Installed Sovereign Workspace.
     * Backed by persistent WebFilesystemSpace_V1 (OPFS/IDB) and user's DomainKeystone.
     */
    private initMode2LocalUserContext;
}
/**
 * Singleton accessor for the WebContextModeService.
 */
export declare function getContextModeService(): WebContextModeService;
//# sourceMappingURL=context-mode-service.d.mts.map