/**
 * Embedding Loader - Load embedding weights.
 *
 * Handles loading of token embedding weights with support for:
 * - GPU and CPU paths
 * - Large weight streaming
 * - F32 to F16 downcast
 * - WeightBuffer wrapping
 *
 * @module loader/embedding-loader
 */

import type {
  WeightBuffer,
  WeightLayout,
  CpuWeightBuffer,
  SplitWeightBuffer,
} from '../gpu/weight-buffer.js';
import type { TensorLocation } from './loader-types.js';

/** Tensor loading function signature */
export type TensorLoader = (
  name: string,
  toGPU?: boolean,
  silent?: boolean
) => Promise<GPUBuffer | WeightBuffer | CpuWeightBuffer | SplitWeightBuffer | Float32Array | Uint8Array | null>;

/**
 * Context required for embedding loading.
 */
export interface EmbeddingLoaderContext {
  /** Tensor locations map */
  tensorLocations: Map<string, TensorLocation>;
  /** Load a tensor by name */
  loadTensor: TensorLoader;
  /** Check if large weight should stream to CPU */
  shouldStreamLargeWeight: (name: string, loc: TensorLocation, label: string) => boolean;
  /** Load a shard byte range for range-backed CPU sources */
  loadShardRange?: (index: number, offset: number, length: number) => Promise<ArrayBuffer>;
  /** Resolve weight layout from location */
  resolveWeightLayout: (loc: TensorLocation) => WeightLayout;
  /** GPU buffers to track for cleanup */
  gpuBuffers: Set<GPUBuffer>;
  /** Keep F32 weights (skip downcast) */
  keepF32Weights: boolean;
  /** Preserve F32 embeddings when manifest quantization requires F32 embedding weights */
  preserveF32Embeddings?: boolean;
  /** Host shader-f16 capability, used to choose CPU F16->F32 fallback on no-f16 devices */
  hostHasShaderF16?: boolean | null;
  /** Manifest-declared embedding kernel identity. */
  embeddingKernel?: {
    kernel?: string;
    entry?: string;
  } | null;
}

/** Result of embedding loading */
export type EmbeddingResult = GPUBuffer | WeightBuffer | CpuWeightBuffer | SplitWeightBuffer | Float32Array | null;

/**
 * Load embedding weights.
 *
 * @param ctx - Embedding loader context
 * @returns Loaded embeddings or null if not found
 */
export declare function loadEmbeddings(ctx: EmbeddingLoaderContext): Promise<EmbeddingResult>;