/**
 * Stable public entry point for the Boids product block.
 * @module three-blocks/boids
 */
import type { Renderer, StorageBufferAttribute, StorageInstancedBufferAttribute, Vector3 } from 'three/webgpu';
/** GPU storage accepted as the initial position source for a flock. */
export type BoidsInitialPositions = StorageBufferAttribute | StorageInstancedBufferAttribute;
/**
 * Stable construction options for a GPU flock.
 *
 * The constructor allocates the flock's GPU storage immediately. An initial position
 * source is copied on the first {@link Boids.step} call and remains owned by the caller.
 */
export interface BoidsOptions {
    /** Number of simulated agents; values are rounded up internally for GPU dispatch. */
    count?: number | undefined;
    /** Whether agents move in three dimensions; `false` constrains motion to the XY plane. */
    is3D?: boolean | undefined;
    /** Axis-aligned dimensions of the simulation domain in world units. */
    domainDimensions?: Vector3 | undefined;
    /** Maximum speed, interpreted relative to the domain when relative parameters are enabled. */
    speedLimit?: number | undefined;
    /** Separation radius, relative to the domain by default. */
    separation?: number | undefined;
    /** Alignment radius, relative to the domain by default. */
    alignment?: number | undefined;
    /** Cohesion radius, relative to the domain by default. */
    cohesion?: number | undefined;
    /** Whether flock distances and speed scale with the average domain dimension. */
    useRelativeParameters?: boolean | undefined;
    /** Whether to collect optional implementation diagnostics; disabled by default. */
    debug?: boolean | undefined;
    /** Whether the engine computes smoothed headings for its internal render integration. */
    useDirection?: boolean | undefined;
    /** Whether the engine computes per-agent transforms for its internal render integration. */
    useMatrices?: boolean | undefined;
    /** Whether to use neighbor-grid acceleration instead of the quadratic fallback. */
    useSpatialGrid?: boolean | undefined;
    /** Multiplier applied to simulation time without changing the host frame delta. */
    timeScale?: number | undefined;
    /** Fixed simulation interval in seconds, or `null` to use the measured frame interval. */
    fixedTimeStep?: number | null | undefined;
    /** Maximum fixed simulation steps performed for one host frame. */
    maxSubsteps?: number | undefined;
    /** Maximum accepted host frame interval in seconds. */
    maxFrameDelta?: number | undefined;
    /** Caller-owned GPU positions copied into engine-owned storage during first use. */
    initialPositions?: BoidsInitialPositions | null | undefined;
    /** Two-component deterministic seed used for initial headings and positions. */
    randomSeed?: readonly [number, number] | null | undefined;
}
/**
 * Stable declaration-facing façade for the Boids GPU engine.
 *
 * The façade is the engine object itself: it adds no wrapper allocation and preserves
 * constructor identity. GPU work is submitted only by {@link Boids.step}. Engine-owned
 * storage is released by {@link Boids.dispose}; dispose the flock before its renderer.
 */
export interface Boids {
    /** Number of live agents advanced by each step. */
    readonly particleCount: number;
    /** Whether the flock is simulated in three dimensions. */
    readonly is3D: boolean;
    /**
     * Resize the axis-aligned simulation domain and synchronize neighbor acceleration.
     * Call between frames, before the next {@link Boids.step}.
     */
    setDomainDimensions(dimensions: Vector3): this;
    /**
     * Enable or disable engine-owned neighbor-grid acceleration.
     * Reconfiguration is synchronous and should happen between frame steps.
     */
    setSpatialGridEnabled(enabled: boolean): this;
    /**
     * Release an engine-created neighbor grid and return to the quadratic neighbor pass.
     * The operation is safe when no grid is enabled and does not dispose caller resources.
     */
    detachSpatialGrid(): this;
    /**
     * Release engine-owned GPU storage, compute passes, and any internally created grid.
     * The renderer, external grids, constraints, initial positions, mesh, geometry, material,
     * and interaction world remain caller-owned. The method is idempotent; do not step afterward.
     */
    dispose(): void;
    /**
     * Advance GPU state for one host frame.
     * Call after updating controls and interaction inputs, await completion, then render.
     * The first call may initialize the renderer and copy initial positions.
     * @throws {Error} If renderer initialization, compute submission, or an active constraint fails.
     */
    step(renderer: Renderer, externalDeltaSeconds?: number | null): Promise<void>;
}
interface BoidsConstructor {
    /**
     * Create a flock and allocate its engine-owned GPU storage.
     * @throws {RangeError} If an option describes an invalid capacity or timestep.
     * @throws {TypeError} If an external initial-position source is incompatible.
     */
    new (options?: BoidsOptions): Boids;
    /** Runtime prototype of the underlying Boids engine. */
    readonly prototype: Boids;
}
/**
 * Construct a stable Boids façade without wrapping or copying the runtime engine.
 * @see Boids
 */
export declare const Boids: BoidsConstructor;
/** Visual helper for inspecting the spatial grid used by the flock. */
export { SpatialGridHelper } from './Simulation/Boids/SpatialGridHelper.js';
/** Stable TSL integration nodes for boid spatial lookups. */
export { spatialLookupInternals } from './Simulation/Boids/compute/helpers.js';