/**
 * Kernel Utilities - Shared utilities for kernel management
 *
 * This module re-exports utilities from specialized submodules:
 * - kernel-configs: Kernel configuration data
 * - shader-cache: Shader loading and compilation
 * - pipeline-cache: Pipeline creation and caching
 * - feature-check: Device capability checking
 * - kernel-tuning: Auto-tuning and prewarming
 * - uniform-utils: Uniform buffer helpers
 *
 * @module gpu/kernels/utils
 */

// ============================================================================
// Re-exports from kernel-configs
// ============================================================================

export {
  type VariantMetadata,
  type KernelConfig,
  KERNEL_CONFIGS,
  getKernelConfig,
  setKernelValidator,
} from './kernel-configs.js';

// ============================================================================
// Re-exports from shader-cache
// ============================================================================

export {
  loadShaderSource,
  compileShader,
  getShaderModule,
  clearShaderCaches,
  getShaderCacheStats,
} from './shader-cache.js';

// ============================================================================
// Re-exports from pipeline-cache
// ============================================================================

export {
  getOrCreateBindGroupLayout,
  getOrCreatePipelineLayout,
  getCachedPipeline,
  getPipelineFast,
  getPipelineBindGroupLayout,
  createPipeline,
  clearPipelineCaches,
  getPipelineCacheStats,
} from './pipeline-cache.js';

// ============================================================================
// Re-exports from feature-check
// ============================================================================

export {
  type FeatureCapabilities,
  hasRequiredFeatures,
  validateAttentionLimits,
} from './feature-check.js';

// ============================================================================
// Re-exports from kernel prewarming
// ============================================================================

export {
  prewarmKernels,
} from './kernel-prewarm.js';

// ============================================================================
// Re-exports from uniform-utils
// ============================================================================

export {
  type UniformBufferOptions,
  createUniformBufferFromData,
  createUniformBufferWithView,
  getUniformByteLength,
  writeUniformsFromObject,
} from './uniform-utils.js';

// ============================================================================
// Combined Cache Management
// ============================================================================

/** Whether debug-only kernel record-stage timing is enabled for this process. */
export declare const RECORD_STAGE_DEBUG_ENABLED: boolean;

/** Debug-only kernel timing recorder enabled by DOPPLER_DBG_RECORD. */
export declare function __dbgRecord(
  op: string,
  variant: string,
  pipelineMs: number,
  prepMs: number,
  bgMs: number,
  dispatchMs: number
): void;

/**
 * Unified kernel dispatch helper. Resolves the kernel config and pipeline
 * for `opName`/`variant`, creates a uniform buffer from `uniforms`, and
 * dispatches via the provided `target` (GPUDevice or CommandRecorder).
 */
export declare function unifiedKernelWrapper(
  opName: string,
  target: GPUDevice | { device: GPUDevice; beginComputePass: unknown } | null,
  variant: string,
  bindings: unknown[],
  uniforms: Record<string, number>,
  workgroups: number | [number, number, number],
  constants?: Record<string, number> | null,
  extraBindings?: unknown[] | null,
  dispatchLabel?: string | null
): Promise<void>;

/**
 * Create a bind group with descriptor validation. Throws a labeled error
 * when the descriptor is missing required fields.
 */
export declare function createBindGroupWithValidation(
  device: GPUDevice,
  descriptor: GPUBindGroupDescriptor,
  contextLabel: string
): GPUBindGroup;

/**
 * Clear all kernel caches
 */
export declare function clearKernelCaches(): void;

/**
 * Alias for clearKernelCaches for backward compatibility
 */
export declare function clearPipelineCache(): void;

/**
 * Get combined cache statistics
 */
export declare function getCacheStats(): {
  pipelines: number;
  shaders: number;
  shaderModules: number;
  bindGroupLayouts: number;
  pipelineLayouts: number;
};