/**
 * Typed worker-local events and frame lifecycle for Three Blocks applications.
 *
 * The dispatcher deliberately does not mirror events across threads. A worker bridge can
 * map its explicit protocol onto this local dispatcher without turning every local event
 * into a public, structured-clone boundary.
 *
 * @module three-blocks/runtime
 */
export type EventName<TEvents extends object> = Extract<keyof TEvents, string>;
export type EventHandler<TPayload> = (payload: TPayload) => void;
export interface TriggerOptions {
    /** Retain the latest payload and replay it to future listeners and components. */
    readonly fireAtStart?: boolean;
}
export interface RafOptions {
    /** Lower priorities run first. Renderers normally use `Infinity`. */
    readonly renderPriority?: number;
    /** `onThrottle` frequency. `Infinity` runs it every frame; values <= 0 disable it. */
    readonly fps?: number;
    /** Optional component-specific delta cap in seconds. */
    readonly maxDelta?: number;
}
export interface FrameTiming {
    readonly delta: number;
    readonly elapsedTime: number;
    readonly startTime: number;
    readonly throttleInterpolation: number;
}
type EmptyFrameValues = Readonly<Record<never, never>>;
type FrameValues<TValues extends object> = Omit<TValues, keyof FrameTiming>;
/**
 * A readonly lifecycle view. One internal object is reused between handlers, so consumers
 * must read it synchronously and must not retain it.
 */
export type FrameContext<TValues extends object = EmptyFrameValues> = Readonly<FrameValues<TValues> & FrameTiming>;
export interface FrameLifecycle<TValues extends object = EmptyFrameValues> {
    readonly raf?: RafOptions;
    onBeforeRaf?(context: FrameContext<TValues>): void | PromiseLike<void>;
    onRaf?(context: FrameContext<TValues>): void | PromiseLike<void>;
    onAfterRaf?(context: FrameContext<TValues>): void | PromiseLike<void>;
    onThrottle?(context: FrameContext<TValues>): void | PromiseLike<void>;
}
/** Event `pointermove` maps to method `onPointermove`; casing after the first letter is retained. */
export type EventMethodMap<TEvents extends object> = {
    [TName in EventName<TEvents> as `on${Capitalize<TName>}`]?: (payload: TEvents[TName]) => void;
};
export type RuntimeComponent<TEvents extends object, TValues extends object = EmptyFrameValues> = FrameLifecycle<TValues> & EventMethodMap<TEvents>;
export interface DispatcherOptions<TValues extends object = EmptyFrameValues> {
    /** Shared renderer/scene/input values copied once into the reused lifecycle contexts. */
    readonly context?: FrameValues<TValues>;
    /** Global frame delta cap in seconds. Defaults to 0.1. */
    readonly maxDelta?: number;
    /** Monotonic clock in seconds. Defaults to `Date.now() / 1000`. */
    readonly clock?: () => number;
}
export interface FrameInput<TValues extends object = EmptyFrameValues> {
    /** Current monotonic time in seconds. */
    readonly now?: number;
    /** Explicit raw delta in seconds. When omitted it is derived from the clock. */
    readonly delta?: number;
    /** Explicit elapsed time in seconds. */
    readonly elapsedTime?: number;
    /** Explicit lifecycle start time in seconds. */
    readonly startTime?: number;
    /** Partial updates for shared lifecycle values. */
    readonly context?: Partial<FrameValues<TValues>>;
}
export interface FixedStepInput<TValues extends object = EmptyFrameValues> {
    readonly context?: Partial<FrameValues<TValues>>;
}
export interface FixedStepReset {
    readonly startTime?: number;
    readonly elapsedTime?: number;
}
/** Typed local dispatcher with retained events and a deterministic frame scheduler. */
export declare class Dispatcher<TEvents extends object, TValues extends object = EmptyFrameValues> {
    #private;
    constructor(options?: DispatcherOptions<TValues>);
    get paused(): boolean;
    on<TName extends EventName<TEvents>>(name: TName, handler: EventHandler<TEvents[TName]>): () => void;
    off<TName extends EventName<TEvents>>(name: TName, handler: EventHandler<TEvents[TName]>): void;
    trigger<TName extends EventName<TEvents>>(name: TName, payload: TEvents[TName], options?: TriggerOptions): void;
    clearRetained<TName extends EventName<TEvents>>(name: TName): void;
    register(component: RuntimeComponent<TEvents, TValues>): () => void;
    unregister(component: RuntimeComponent<TEvents, TValues>): void;
    isRegistered(component: RuntimeComponent<TEvents, TValues>): boolean;
    /** Call after changing a registered component's `raf.renderPriority`. */
    invalidateRenderOrder(): void;
    setContext(values: Partial<FrameValues<TValues>>): void;
    pause(): void;
    resume(): void;
    /** Run one clock-driven frame. The first frame after construction/resume receives delta 0. */
    runFrame(input?: FrameInput<TValues>): Promise<void>;
    /** Advance without consulting wall time. Repeated calls are deterministic. */
    fixedStep(delta: number, input?: FixedStepInput<TValues>): Promise<void>;
    resetFixedStep(reset?: FixedStepReset): void;
}
export declare function createDispatcher<TEvents extends object, TValues extends object = EmptyFrameValues>(options?: DispatcherOptions<TValues>): Dispatcher<TEvents, TValues>;
export {};