/**
 * Interface for a service that can be registered with the Locator.
 *
 * Services implementing this interface are expected to have:
 * - a unique `serviceType` string (must match one of the keys in Locator._services),
 * - a `name` for identification (optional for runtime usage but required by interface),
 * - and a `dispose()` method for cleanup (e.g., removing event listeners or destroying resources).
 *
 * Example usage in Locator:
 *
 * ```ts
 * Locator.provide(new CustomAudioService());
 * const audio = Locator.audio;
 * audio.play("sound.mp3");
 * ```
 */
export interface Service
{
    /** The name of the service instance. Can be used for debugging or logging. */
    name: string;

    /**
     * The unique type identifier of the service.
     * Must correspond to one of the supported keys in Locator._services,
     * e.g., "user", "clock", "renderer2D", "network", "viewport", etc.
     */
    serviceType: string;

    /**
     * Called when the service is no longer needed.
     * Should perform necessary cleanup like removing event listeners or releasing resources.
     */
    dispose(): void;
}

/**
 * Configuration object for initializing the Viewport.
 *
 * Defines the virtual resolution to which the content is scaled.
 * The height is always fully visible on screen, and the width may be cropped to fit.
 */
export interface ViewportOptions
{
    /** The virtual width of the viewport in pixels. Used as the base logical width for layout and scaling. */
    width: number;
    /**
     * The virtual height of the viewport in pixels.
     * This height is always fully visible and used as the base for scaling.
     */
    height: number;
}

/**
 * Payload emitted with the "resize" event from the Viewport.
 *
 * Contains information about the current layout, scale, and visible area
 * after a resize operation.
 */
export interface ResizeEventDetail
{
    /** The full virtual width of the viewport (same as options.width). */
    viewportWidth: number;
    /** The full virtual height of the viewport (same as options.height). */
    viewportHeight: number;
    /** The width of the visible area after cropping, in virtual units. */
    visibleWidth: number;
    /** The visible height of the viewport, always equal to `viewportHeight`. */
    visibleHeight: number;
    /** The virtual center point of the visible area. */
    center: { x: number; y: number };
    /** The virtual x-coordinate of the left edge of the visible area. */
    left: number;
    /** The virtual x-coordinate of the right edge of the visible area. */
    right: number;
    /**
     * Ratio of the visible width to the total virtual width (clamped between 0.2 and 1).
     * Indicates how much of the horizontal content is currently visible.
     */
    cropWidthRatio: number;
    /** Scale factor applied to the scene based on screen height. Computed as: `window.innerHeight / viewportHeight`. */
    heightRatio: number;
}
