/**
 * @module types
 *
 * Shared type definitions for ibgib-based frontend apps.
 *
 * ## notes
 *
 * Three layers of globalThis state:
 *   IbGibGlobalThisInfo          (@ibgib/web-gib — the root ibgib slot)
 *       └── IbGibGlobalThis_Common     (bootstrap promise tracking)
 *               └── IbGibGlobalThis_IbGibApp  (all ibgib App witness apps)
 *                       └── IbGibGlobalThis_[AppName]   (per-app extensions)
 */

import { IbGibRel8ns_V1, IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
import { CommentData_V1 } from "@ibgib/core-gib/dist/common/comment/comment-types.mjs";
import { RCLIArgInfo } from "@ibgib/helper-gib/dist/rcli/rcli-types.mjs";

import { LiveProxyIbGib } from "../witness/live-proxy-ibgib/live-proxy-ibgib-one-file.mjs";
import { IbGibGlobalThisInfo } from "../types.mjs";

// ---------------------------------------------------------------------------
// App ambient context config
// ---------------------------------------------------------------------------

/**
 * Configuration object that parameterizes an ibgib app's storage substrates.
 *
 * This is the primary seam between the framework layer and a specific app.
 * Every downstream app creates exactly one APP_CONFIG and passes it to the
 * framework helpers.
 *
 * ## notes
 *
 * Intended to be upstreamed into @ibgib/web-gib.
 */
export interface IbGibAmbientContextConfig {
    /** Target IndexedDB database name */
    dbName: string;
    /** Primary object store name */
    storeName: string;
    /** Additional stores to initialize alongside the primary (e.g., ZERO_SPACE_ID) */
    additionalStoreNames?: string[];
    /** The IndexedDB key under which the AI API key is persisted */
    apiKeyName: string;
}

// ---------------------------------------------------------------------------
// Space shim (RCLI pathing compat layer)
// ---------------------------------------------------------------------------

/**
 * Per-space shim that mimics a filesystem CWD context for ibgib RCLI compat.
 */
export interface SpaceShimGlobalInfo {
    /**
     * The initial cwd() value when the RCLI was started. Used as the context
     * path the user types commands from.
     */
    initialCwd: string;
    /** The active CWD, updated by pass-through `cd` commands. */
    cwd: string;
}

// ---------------------------------------------------------------------------
// Bootstrap request comment (RCLI plumbing)
// ---------------------------------------------------------------------------

/** @see {@link RequestCommentIbGib_V1} */
export interface RequestCommentData_V1 extends CommentData_V1 {
    /** As close to the raw args as we can get. */
    args: string[];
    /** Interpreted infos for args. */
    interpretedArgInfos: RCLIArgInfo[];
}

export interface RequestCommentRel8ns_V1 extends IbGibRel8ns_V1 { }

/**
 * Special Comment ibgib that acts as a "request" — the command analog from RCLI.
 *
 * The raw text of the command is `text` from `CommentData_V1`.
 */
export interface RequestCommentIbGib_V1
    extends IbGib_V1<RequestCommentData_V1, RequestCommentRel8ns_V1> {
    /** Kluge for one-off commandlines during initial development. */
    oneOff: boolean;
}

// ---------------------------------------------------------------------------
// Identity (optional — WIP as of April 2026)
// ---------------------------------------------------------------------------

/**
 * Framework-level identity interface.
 *
 * ## design notes
 *
 * The implementation is entirely consumer-supplied. The framework defines only
 * the shape of the slot so shells and components can react to auth state
 * without coupling to a specific identity mechanism.
 *
 * For ibgib apps, the typical implementation will be keystone-based (a Merkle
 * DAG proof of cryptographic identity continuity), not token-based.
 *
 * ## WIP caveat (atow April 2026)
 *
 * The keystone identity implementation in @ibgib/core-gib is still under
 * active development. This interface represents the intended framework
 * contract. Check the ibgib-libs sync/keystone module for the current
 * implementation status before using.
 */
export interface IbGibIdentityContext {
    /** Whether identity resolution has completed (does not imply authenticated). */
    resolved?: boolean;
    /** Whether the current session has a verified identity. */
    authenticated?: boolean;
    domainIdentity?: any;
    syncDelegateIdentity?: any;
    tjpAddr?: string;
    username?: string;
    handle?: string;
    aggregateDetails?: any;
    /**
     * App-specific identity payload.
     * For ibgib: typically `{ keystoneAddr, userIbGibAddr }`.
     */
    data?: Record<string, any>;
}

// ---------------------------------------------------------------------------
// UI Shell
// ---------------------------------------------------------------------------

/**
 * Minimal interface for an application's UI Shell.
 *
 * ## design notes
 *
 * This is intentionally minimal to avoid coupling the bootstrap engine to a
 * specific UI design (header, panels, etc.).
 */
export interface IbGibAppShell {
    /**
     * Hook called by the bootstrap engine when the ibGib engine and metaspace
     * are fully initialized and ready for interaction.
     */
    onEngineReady(): void;
}

// ---------------------------------------------------------------------------
// GlobalThis layers
// ---------------------------------------------------------------------------

/**
 * Layer 1: Fields shared across ALL ibgib web apps.
 *
 * Extends IbGibGlobalThisInfo from @ibgib/web-gib (the root ibgib slot).
 * Intended to be upstreamed into @ibgib/web-gib.
 */
export interface IbGibGlobalThis_Common extends IbGibGlobalThisInfo {
    /**
     * Set to true when bootstrap has been triggered.
     * There is no "bootstrapComplete" — await {@link bootstrapPromise} instead.
     */
    bootstrapStarted?: boolean;
    /**
     * The promise returned by the bootstrap function. Components await this
     * to defer initialization until the App witness and metaspace are ready.
     */
    bootstrapPromise?: Promise<void>;
    /**
     * Singleton chronologys component. Should not be destroyed for the
     * duration of the page session.
     */
    chronologysComponent?: any;
}

/**
 * Layer 2: Fields shared by any app that follows the ibgib App witness pattern.
 *
 * Apps using the bootstrap factory pattern extend this interface and add only
 * their app-specific fields.
 *
 * ## notes
 *
 * Intended to be upstreamed into @ibgib/web-gib as IbGibGlobalThis_IbGibApp.
 */
export interface IbGibGlobalThis_IbGibApp extends IbGibGlobalThis_Common {
    /** Semver string generated at build time. */
    version?: string;
    /** 
     * The application's UI Shell service. 
     * Initialized by the consumer and registered on the globalThis.
     */
    shell?: IbGibAppShell;
    /** Per-space RCLI pathing shim. */
    spaceShim: { [spaceId: string]: SpaceShimGlobalInfo };
    /** When true, verbose output is enabled for the session. */
    verbose?: boolean;
    /**
     * Looks up the AI API key from IndexedDB storage.
     * Stored as a function so the key is never cached in memory at the global level.
     */
    fnDefaultGetAPIKey: () => Promise<string>;
    /** The initial "command" comment ibgib created at bootstrap time. */
    initialCommentIbGib?: IbGib_V1;
    /** Live proxy wrapping {@link initialCommentIbGib} for reactive subscriptions. */
    initialCommentIbGibProxy?: LiveProxyIbGib;
    /**
     * Optional identity context. Populated by the consumer's resolveIdentity()
     * callback in the bootstrap options.
     *
     * - `undefined`: no identity mechanism configured
     * - `null`: identity resolution was attempted; user is unauthenticated
     * - `IbGibIdentityContext`: identity resolved (check `.authenticated`)
     *
     * @see {@link IbGibIdentityContext}
     */
    identity?: IbGibIdentityContext | null;
}