/**
 * @module ui/router/cosmos/cosmos-router-types
 *
 * Types and interfaces for the Universal Cosmos & Galaxy Archetype Router.
 * Supports dual routing mechanisms:
 * 1. Space-Qualified Raw Addr (Content-Addressed & Space-Scoped):
 *    - Snapshot: /:cosmos/:spaceId/addr/:ibGibAddr
 *    - Living Timeline Tip: /:cosmos/:spaceId/tjp/:tjpAddr
 * 2. Workspace / Galaxy Archetype Projections:
 *    - Polycosmos: / or /polycosmos or /@:siteUsername or /keystone/:keystoneTjp
 *    - Cosmos: /:cosmos or /@:siteUsername/:cosmos
 *    - Branching Galaxy: /:cosmos/:galaxy[/:branch[/*filePath]]
 *    - Linear Galaxy: /:cosmos/:galaxy[/tjp/*trail] or [/addr/*trail]
 */

import { CosmosIbGib_V1 } from '@ibgib/core-gib/dist/cosmology/cosmos/cosmos-types.mjs';
import { GalaxyPolicy } from '@ibgib/core-gib/dist/cosmology/galaxy/galaxy-types.mjs';
import { RouterNavigateOptions, RouteListener } from '../router-types.mjs';

export { RouterNavigateOptions, RouteListener };

export type CosmosTenant =
    | { type: 'username'; siteUsername: string }
    | { type: 'keystone'; keystoneTjp: string };

export interface CosmosRouteBase {
    tenant?: CosmosTenant;
}

export interface PolycosmosRouteInfo extends CosmosRouteBase {
    kind: 'polycosmos';
}

export interface CosmosOnlyRouteInfo extends CosmosRouteBase {
    kind: 'cosmos';
    cosmos: string;
}

export interface CosmosGalaxyRouteInfo extends CosmosRouteBase {
    kind: 'galaxy';
    cosmos: string;
    galaxy: string;
    topology: 'branching' | 'linear';
    discriminator?: string;
    policy?: GalaxyPolicy;
    branch?: string;
    filePath?: string;
    trailMode?: 'tjp' | 'addr';
    trail?: string[];
    topicTjp?: string;
    query?: Record<string, string>;
}

export interface CosmosRawAddrRouteInfo extends CosmosRouteBase {
    kind: 'raw-addr';
    cosmos: string;
    spaceId: string;
    ibGibAddr: string;
    query?: Record<string, string>;
}

export interface CosmosRawTjpRouteInfo extends CosmosRouteBase {
    kind: 'raw-tjp';
    cosmos: string;
    spaceId: string;
    tjpAddr: string;
    query?: Record<string, string>;
}

export type CosmosRouteInfo =
    | PolycosmosRouteInfo
    | CosmosOnlyRouteInfo
    | CosmosGalaxyRouteInfo
    | CosmosRawAddrRouteInfo
    | CosmosRawTjpRouteInfo;

export interface ParseCosmosRouteOptions {
    /**
     * Optional loaded Cosmos manifest for Option B O(1) content-addressed policy retrieval.
     */
    cosmosManifest?: CosmosIbGib_V1;
}

/**
 * Async provider function to load a Cosmos manifest from CAS or remote space on demand.
 */
export type CosmosManifestProvider = (
    cosmosName: string,
    tenant?: CosmosTenant,
) => Promise<CosmosIbGib_V1 | undefined>;