/**
 * @holoscript/core/traits — Trait System Type Declarations
 */

export interface Trait {
  name: string;
  [key: string]: any;
}

export interface HostCapabilities {
  fileSystem?: HostFileSystemCapabilities;
  process?: HostProcessCapabilities;
  network?: HostNetworkCapabilities;
}

export interface HostFileSystemCapabilities {
  readFile(path: string): Promise<string>;
  writeFile(path: string, content: string): Promise<void>;
  listDir(path: string): Promise<string[]>;
  exists(path: string): Promise<boolean>;
}

export interface HostProcessCapabilities {
  exec(command: string, options?: HostExecOptions): Promise<HostExecResult>;
}

export interface HostExecOptions {
  cwd?: string;
  timeout?: number;
  env?: Record<string, string>;
}

export interface HostExecResult {
  stdout: string;
  stderr: string;
  exitCode: number;
}

export interface HostNetworkCapabilities {
  fetch(url: string, options?: HostNetworkRequestOptions): Promise<HostNetworkResponse>;
}

export interface HostNetworkRequestOptions {
  method?: string;
  headers?: Record<string, string>;
  body?: string;
  timeout?: number;
}

export interface HostNetworkResponse {
  status: number;
  headers: Record<string, string>;
  body: string;
}

export interface TraitContext {
  node: any;
  emit(event: string, payload?: any): void;
  getState(): Record<string, any>;
  setState(updates: Record<string, any>): void;
  hostCapabilities?: HostCapabilities;
  [key: string]: any;
}

export type TraitEvent = {
  type: string;
  [key: string]: any;
};

export interface TraitHandler<T = any> {
  name: string;
  defaultConfig?: T;
  onAttach?: (node: any, config: T, context: TraitContext) => void | Promise<void>;
  onDetach?: (node: any, config: T, context: TraitContext) => void | Promise<void>;
  onUpdate?: (node: any, config: T, context: TraitContext, delta: number) => void | Promise<void>;
  onEvent?: (node: any, config: T, context: TraitContext, event: TraitEvent) => void | Promise<void>;
  [key: string]: any;
}

export declare const SEMANTIC_CUSTODY_SCHEMA: 'holoscript.semantic-custody.v2';
export interface SemanticCustodyBindingV2 {
  schema: typeof SEMANTIC_CUSTODY_SCHEMA;
  message_id: string;
  action: string;
  sender: string;
  recipient: string;
  nonce: string;
  axis_1_id: string;
  axis_2_id: string;
  payload_digest: string;
  surface_id: string;
  holokey: string;
}
export interface HoloMeshSignedSemanticEnvelope {
  body: SemanticCustodyBindingV2;
  signature: string;
  signer_address: string;
  nonce: string;
  timestamp: string;
}
export interface SemanticCustodyEnvelope {
  schema: typeof SEMANTIC_CUSTODY_SCHEMA;
  signed: HoloMeshSignedSemanticEnvelope;
}
export interface SemanticCustodyMessageLike {
  version: '2.0';
  message_id: string;
  from: string;
  to: string;
  created_at_ms: number;
  action: string;
  nonce: string;
  pillar_slice: {
    axis_1_id: string;
    axis_2_id: string;
  };
  provenance: {
    surface_id: string;
    holokey: string;
    signer_address: string;
  };
  brain_coord?: unknown;
  receipt?: unknown;
  scene_delta?: unknown;
  task_state?: unknown;
  confidence?: number;
  payload?: Record<string, unknown>;
  parallel_slice?: unknown;
  text_boundary?: string;
  custody?: SemanticCustodyEnvelope;
}
export interface SemanticCustodyVerification {
  valid: boolean;
  signer: string | null;
  reason?: string;
}
export type SemanticCustodyVerifier = (
  envelope: HoloMeshSignedSemanticEnvelope
) => Promise<SemanticCustodyVerification>;
export interface SemanticReplayStore {
  claim(signer: string, nonce: string): boolean | Promise<boolean>;
}
export declare class InMemorySemanticReplayStore implements SemanticReplayStore {
  claim(signer: string, nonce: string): boolean;
  clear(): void;
}
export type SemanticCustodyFailureReason =
  | 'missing-custody'
  | 'schema-version'
  | 'binding-mismatch'
  | 'payload-digest'
  | 'signature'
  | 'signer-mismatch'
  | 'replay';
export interface SemanticCustodyReceipt {
  schema: 'holoscript.semantic-custody-receipt.v1';
  accepted: true;
  message_id: string;
  action: string;
  sender: string;
  recipient: string;
  nonce: string;
  signer_address: string;
  payload_digest: string;
  receipt_digest: string;
}
export type SemanticCustodyAdmission =
  | { ok: true; receipt: SemanticCustodyReceipt }
  | { ok: false; reason: SemanticCustodyFailureReason; detail?: string };
export declare function computeSemanticPayloadDigest(
  message: SemanticCustodyMessageLike
): Promise<string>;
export declare function buildSemanticCustodyBinding(
  message: SemanticCustodyMessageLike
): Promise<SemanticCustodyBindingV2>;
export declare function admitSemanticCustodyMessage(
  message: SemanticCustodyMessageLike,
  options: {
    verifySignedEnvelope: SemanticCustodyVerifier;
    replayStore: SemanticReplayStore;
  }
): Promise<SemanticCustodyAdmission>;
export declare function getSemanticCustodyReceipt(
  message: object
): SemanticCustodyReceipt | undefined;

export type PerceptualColorMode = 'auto' | 'palette' | 'gradient' | 'color_map';
export interface PerceptualGradientStop { t: number; color: string; }
export interface PerceptualColorConfig {
  mode: PerceptualColorMode;
  palette: string[];
  gradient: PerceptualGradientStop[];
  color_map: string;
  steps: number;
  dampening: number;
  target_delta_e: number;
  neutral_axis: boolean;
  scientific: boolean;
  emit_analysis: boolean;
}
export interface PerceptualColorAnalysis {
  color: string;
  lightness: number;
  chroma: number;
  hue: number;
  nearestNeutral: string;
}
export interface PerceptualColorTraitOutput {
  mode: PerceptualColorMode;
  palette?: string[];
  gradient?: PerceptualGradientStop[];
  colorMap?: string;
  analysis?: PerceptualColorAnalysis[];
  compilerColorPass: any;
}
export interface PerceptualColorState {
  revisions: number;
  lastApplied: PerceptualColorTraitOutput | null;
}
export const perceptualColorHandler: TraitHandler<PerceptualColorConfig>;

export type MeshClassification =
  | 'none'
  | 'wall'
  | 'floor'
  | 'ceiling'
  | 'table'
  | 'seat'
  | 'window'
  | 'door'
  | 'stairs'
  | 'bed'
  | 'counter'
  | 'unknown';
export interface RealityKitMeshConfig {
  mesh_classification: boolean;
  physics_enabled: boolean;
  occlusion_enabled: boolean;
  collision_margin: number;
  update_frequency: number;
  max_anchor_distance: number;
  render_wireframe: boolean;
}
export const realityKitMeshHandler: TraitHandler<RealityKitMeshConfig>;

export type RoomMeshResolution = 'low' | 'medium' | 'high';
export type SemanticSurface = 'floor' | 'wall' | 'ceiling' | 'furniture' | 'unknown';
export interface RoomMeshConfig {
  resolution: RoomMeshResolution;
  update_rate: number;
  semantic_labeling: boolean;
  room_boundary_detection: boolean;
  physics_collider: boolean;
  merge_adjacent_blocks: boolean;
  visible: boolean;
  wireframe: boolean;
}
export const roomMeshHandler: TraitHandler<RoomMeshConfig>;

export type ReconstructionMode =
  | 'realtime'
  | 'high_fidelity'
  | 'room_scan'
  | 'object_scan'
  | 'semantic_mesh';
export type MeshDetail = 'low' | 'medium' | 'high';
export type SemanticLabel =
  | 'floor'
  | 'ceiling'
  | 'wall'
  | 'table'
  | 'chair'
  | 'window'
  | 'door'
  | 'unknown';
export interface SceneReconstructionConfig {
  reconstruction_mode: ReconstructionMode;
  mesh_detail: MeshDetail;
  semantic_labeling: boolean;
  physics_collision: boolean;
  occlusion_enabled: boolean;
  update_interval_ms: number;
  max_mesh_faces: number;
}
export const sceneReconstructionHandler: TraitHandler<SceneReconstructionConfig>;

export interface AccessibilityContext {
  screenReader?: boolean;
  highContrast?: boolean;
  motionReduced?: boolean;
}

export interface VRContext {
  headset?: string;
  controllers?: any[];
  handTracking?: boolean;
}

export class VRTraitRegistry {
  register(handler: TraitHandler): void;
  unregister(name: string): void;
  get(name: string): TraitHandler | undefined;
  getHandler(name: string): TraitHandler | undefined;
  getAll(): TraitHandler[];
  handleEventForAllTraits(node: any, ctx: TraitContext, event: TraitEvent): void;
}

export const vrTraitRegistry: VRTraitRegistry;

export interface TraitPlatformSupport {
  platform: string;
  supported: boolean;
  notes?: string;
}

export interface TraitMatrixEntry {
  traitName: string;
  platforms: TraitPlatformSupport[];
}

export interface TraitSupportMatrixData {
  entries: TraitMatrixEntry[];
  generatedAt: string;
}

export function generateTraitSupportMatrix(traitDir: string): Promise<TraitSupportMatrixData>;
export function matrixToJSON(matrix: TraitSupportMatrixData): string;
export function matrixToYAML(matrix: TraitSupportMatrixData): string;

export interface Memory {
  id: string;
  key: string;
  content: string;
  tags: string[];
  embedding: number[] | null;
  createdAt: number;
  accessedAt: number;
  accessCount: number;
  ttl: number | null;
  source: string;
}

export interface MemoryRecallResult {
  memory: Memory;
  score: number;
}

export interface AgentMemoryConfig {
  max_memories: number;
  default_ttl: number | null;
  embedding_model: 'local' | 'openai' | 'none';
  embedding_dim: number;
  auto_compress: boolean;
  compress_prompt: string;
  sync_to_postgres: boolean;
  postgres_url: string;
  db_name: string;
}

export interface AgentMemoryState {
  memories: Map<string, Memory>;
  db: IDBDatabase | null;
  isReady: boolean;
  totalStored: number;
  totalRecalled: number;
  totalCompressed: number;
}

export const agentMemoryHandler: TraitHandler<AgentMemoryConfig>;

export interface JEPAPredictorConfig {
  latentDim: number;
  condDim: number;
}

export interface JEPAPredictorWeights {
  W1: Float32Array;
  b1: Float32Array;
  W2: Float32Array;
  b2: Float32Array;
}

export interface JEPAPredictorForwardResult {
  predicted: Float32Array;
  hidden: Float32Array;
}

export class JEPAPredictor {
  readonly latentDim: number;
  readonly condDim: number;
  constructor(config: JEPAPredictorConfig, weights?: JEPAPredictorWeights);
  forward(contextEmb: Float32Array, conditioning?: Float32Array | null): JEPAPredictorForwardResult;
  setWeights(weights: JEPAPredictorWeights): void;
  getWeights(): Readonly<JEPAPredictorWeights>;
  plan(currentState: string, candidateActions: string[]): {
    action: string;
    predicted: Float32Array;
    confidence: number;
  };
}

export class TraitCompositor {
  [key: string]: any;
}

export declare const COMPOSITION_RULES: any;

export class ECSWorld {
  [key: string]: any;
}

export declare const ComponentType: any;

export class MoMETraitDatabase {
  [key: string]: any;
}

export interface EmergentSpacetimeConfig {
  initial_voxels?: number;
  max_voxels?: number;
  seed?: number;
  force_layout_guard?: boolean;
  ricci_error_bound?: number;
  ricci_heatmap?: boolean;
  loop_threshold?: number;
  real_time_budget_ms?: number;
}

export interface EmergentSpacetimeState {
  network: {
    voxels: Map<string, any>;
    edges: any[];
    loopCount: number;
  };
  hubbleCorrection: number;
  violationCount: number;
  lastRicciError: number;
  isSimulating: boolean;
}

export const emergentSpacetimeHandler: TraitHandler<EmergentSpacetimeConfig>;

export interface NormalizedFaceLandmark {
  x: number;
  y: number;
  z?: number;
  visibility?: number;
  presence?: number;
}
export interface WebcamGazeSample {
  gaze_x: number;
  gaze_y: number;
  foveal_center: [number, number];
  confidence: number;
  timestamp: number;
  source: 'webcam';
}
export interface WebcamGazeConfig {
  auto_start: boolean;
  video_width: number;
  video_height: number;
  sample_rate_hz: number;
  confidence_threshold: number;
  wasm_base_path: string;
  model_asset_path: string;
  gaze_gain_x: number;
  gaze_gain_y: number;
  max_ray_angle_degrees: number;
}
export const DEFAULT_WEBCAM_GAZE_CONFIG: WebcamGazeConfig;
export class WebcamGazeTracker {
  constructor(options: {
    config: WebcamGazeConfig;
    videoElement?: HTMLVideoElement | null;
    onSample: (sample: WebcamGazeSample) => void;
    onError?: (error: Error) => void;
  });
  getStream(): MediaStream | null;
  getVideoElement(): HTMLVideoElement | null;
  start(): Promise<void>;
  stop(): void;
}
export function estimateWebcamGazeFromLandmarks(
  landmarks: readonly NormalizedFaceLandmark[],
  config?: Partial<WebcamGazeConfig>
): WebcamGazeSample | null;
export function webcamGazeToRay(
  sample: Pick<WebcamGazeSample, 'foveal_center'>,
  maxAngleDegrees?: number
): [number, number, number];
export const webcamGazeHandler: TraitHandler<WebcamGazeConfig>;

// ── Domain plugins are NOT re-exported from core ──────────────────────────────
// Core must not statically depend on domain plugins — plugins are data, not code
// (CLAUDE.md / NORTH_STAR). Re-exporting them (even type-only) forced every
// consumer of '@holoscript/core/traits' to resolve each plugin's types, which
// point at source, dragging ~189 plugin source files (incl. .tsx importing
// react/three) into slim builds → TS2307 (broke Studio deploy 2026-05-26).
// Import a plugin directly from its own package, e.g. '@holoscript/radio-astronomy-plugin'.

// ── Quantum-Inspired optimization trait ──────────────────────────────────────
// (packages/core/src/traits/QuantumInspiredTrait.ts)

/** Minimal subset of SnnAccelerator the trait depends on. */
export interface SnnAcceleratorLike {
  readonly available: boolean;
  initialize(opts?: { enableSnn?: boolean; snnTimesteps?: number }): Promise<void>;
  encode(histogram: Float32Array): Promise<Float32Array>;
  dispose(): void;
}

/** Factory that constructs an SnnAcceleratorLike instance on demand. */
export type SnnAcceleratorProvider = () => SnnAcceleratorLike;

export interface QuantumInspiredConfig {
  /** Number of LIF neurons for population coding. Default: 128. */
  numNeurons: number;
  /** Scalar learning-rate exposed to .hs authors. Default: 0.01. */
  learningRate: number;
  /** LIF simulation timesteps per encode call. Default: 50. */
  snnTimesteps: number;
  /**
   * Optional factory for a concrete SnnAcceleratorLike.
   * Inject () => new SnnAccelerator() from @holoscript/holoembed for GPU.
   * Omit for pure-CPU sigmoid fallback.
   */
  acceleratorProvider?: SnnAcceleratorProvider;
}

export declare const quantumInspiredHandler: TraitHandler<QuantumInspiredConfig>;