/**
 * Serializable contracts for transport packs.
 *
 * These types deliberately contain data only: no classes, dates, maps, or
 * three.js values. A pack can therefore cross an HTTP boundary, live in a
 * Worker, or be recorded for a deterministic replay without translation.
 */

/** A WGS84-like geographic position in decimal degrees. */
export interface GeographicPoint {
  lat: number;
  lng: number;
}

/** The road system responsible for a segment. */
export type RoadKind = "interstate" | "us-highway" | "connector";

/** Why a node exists in the deliberately sparse corridor graph. */
export type TransportNodeKind = "terminus" | "waypoint" | "junction";

export interface TransportNode {
  id: string;
  label: string;
  kind: TransportNodeKind;
  position: GeographicPoint;
  /** Human-readable origin and accuracy note for this authored coordinate. */
  provenance: string;
}

/**
 * A directed driveable edge. Reverse itineraries traverse the same edge in
 * reverse; geometry is intentionally not duplicated for each direction.
 */
export interface TransportSegment {
  id: string;
  fromNodeId: string;
  toNodeId: string;
  /** The name a route badge or itinerary should show. */
  roadName: string;
  kind: RoadKind;
  /** Coarse simulation envelope, not live traffic or navigation advice. */
  speedLimitMph: number;
  /** Number of through lanes in one direction at the representative section. */
  lanesPerDirection: number;
  provenance: string;
}

/** A named, ordered itinerary through the segment graph. */
export interface TransportRoute {
  id: string;
  label: string;
  description: string;
  fromNodeId: string;
  toNodeId: string;
  segmentIds: readonly string[];
  provenance: string;
}

interface AnchorBase {
  id: string;
  label: string;
  /** Nearest corridor node used to enter or leave the large-scale simulation. */
  nodeId: string;
  /** Exact transition marker; it need not lie on the corridor centreline. */
  position: GeographicPoint;
  provenance: string;
}

export interface CityTransportAnchor extends AnchorBase {
  kind: "city";
  cityId: string;
}

export interface OfficeTransportAnchor extends AnchorBase {
  kind: "office";
  cityId: string;
  officeId: string;
}

export type TransportAnchor = CityTransportAnchor | OfficeTransportAnchor;

/** A complete coarse world graph and its links to finer Tera scenes. */
export interface TransportPack {
  id: string;
  name: string;
  schemaVersion: 1;
  description: string;
  nodes: readonly TransportNode[];
  segments: readonly TransportSegment[];
  routes: readonly TransportRoute[];
  anchors: readonly TransportAnchor[];
  /** Pack-wide authorship and fitness-for-purpose notices. */
  provenance: readonly string[];
}
