/**
 * @fileoverview Type definitions for HoloScript Core (v5.0)
 * @module @holoscript/core
 */

import type {
  UnknownFieldLowering,
  UAALContainmentIR,
  UAALContainmentQuery,
  UAALContainmentRelation,
  UAALSemanticEntity,
} from '@holoscript/meaning';

// ============================================================================
// CORE TYPES
// ============================================================================

export interface ASTNode {
  type: string;
  [key: string]: any;
}

export interface ParseResult {
  success?: boolean;
  ast: any;
  errors: any[];
  warnings: any[];
}

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

export type SRGB = readonly [r: number, g: number, b: number];
export type LinearRGB = readonly [r: number, g: number, b: number];
export type XYZ = readonly [x: number, y: number, z: number];

export interface Lab {
  L: number;
  a: number;
  b: number;
}

export interface PerceptualDistanceOptions {
  dampening?: number;
  steps?: number;
}
export type LabMetricTensor = readonly [
  readonly [number, number, number],
  readonly [number, number, number],
  readonly [number, number, number],
];
export interface DeltaE2000MetricTensorOptions {
  epsilon?: number;
  regularization?: number;
}
export interface DeltaE2000GeodesicOptions extends DeltaE2000MetricTensorOptions {
  segments?: number;
  iterations?: number;
  stepSize?: number;
  gradientStep?: number;
  maxCoordinateStep?: number;
  clampLab?: boolean;
}
export interface DeltaE2000GeodesicResult {
  path: Lab[];
  length: number;
  straightLength: number;
  energy: number;
  iterations: number;
}
export interface LanlGrayAchromaticAggregate {
  Ls: number;
  Lt1: number;
  Lt2: number;
  count: number;
  choseT2: number;
}
export interface LanlGrayChoiceModelOptions {
  dampening?: number;
  noise?: number;
}
export interface LanlGrayFitOptions {
  dampeningCandidates?: readonly number[];
  noiseCandidates?: readonly number[];
}
export interface LanlGrayFitResult {
  dampening: number;
  noise: number;
  negativeLogLikelihood: number;
  meanAccuracy: number;
  rows: number;
}

export const DAMPENING_OFF: number;
export const DEFAULT_DAMPENING: number;
export const DEFAULT_LANL_GRAY_NOISE: number;

export function srgbToLinearChannel(c: number): number;
export function linearToSrgbChannel(c: number): number;
export function srgbToLinear(rgb: SRGB): LinearRGB;
export function linearToSrgb(rgb: LinearRGB): SRGB;
export function linearRgbToXyz(rgb: LinearRGB): XYZ;
export function xyzToLinearRgb(xyz: XYZ): LinearRGB;
export function xyzToLab(xyz: XYZ): Lab;
export function labToXyz(lab: Lab): XYZ;
export function srgbToLab(rgb: SRGB): Lab;
export function labToSrgb(lab: Lab): SRGB;
export function deltaE2000(lab1: Lab, lab2: Lab): number;
export function dampen(x: number, tau?: number): number;
export function arcLengthDeltaE2000(A: Lab, B: Lab, steps?: number): number;
export function metricTensorDeltaE2000(center: Lab, options?: DeltaE2000MetricTensorOptions): LabMetricTensor;
export function labMetricQuadraticForm(vector: readonly [number, number, number], metric: LabMetricTensor): number;
export function metricTensorArcLengthDeltaE2000(A: Lab, B: Lab, steps?: number, options?: DeltaE2000MetricTensorOptions): number;
export function solveDeltaE2000Geodesic(A: Lab, B: Lab, options?: DeltaE2000GeodesicOptions): DeltaE2000GeodesicResult;
export function lanlGrayChoiceProbability(row: Pick<LanlGrayAchromaticAggregate, 'Ls' | 'Lt1' | 'Lt2'>, options?: LanlGrayChoiceModelOptions): number;
export function lanlGrayNegativeLogLikelihood(rows: readonly LanlGrayAchromaticAggregate[], options?: LanlGrayChoiceModelOptions): number;
export function lanlGrayMeanAccuracy(rows: readonly LanlGrayAchromaticAggregate[], options?: LanlGrayChoiceModelOptions): number;
export function fitLanlGrayAchromaticModel(rows: readonly LanlGrayAchromaticAggregate[], options?: LanlGrayFitOptions): LanlGrayFitResult;
export function perceptualDistance(a: SRGB, b: SRGB, options?: PerceptualDistanceOptions): number;
export function nearestNeutral(c: SRGB): SRGB;
export function lightness(c: SRGB): number;
export function chroma(c: SRGB): number;
export function hue(c: SRGB): number;
export function perceptualLerp(a: SRGB, b: SRGB, t: number): SRGB;
export const LANL_GRAY_ACHROMATIC_SOURCE: {
  readonly repo: string;
  readonly dataUrl: string;
  readonly path: string;
  readonly sha: string;
  readonly columns: readonly string[];
  readonly license: string;
  readonly deposited: string;
  readonly note: string;
};
export const LANL_GRAY_ACHROMATIC_AGGREGATES: readonly LanlGrayAchromaticAggregate[];

export type PerceptualColorPassSource = 'palette' | 'gradient' | 'color_map';
export type PerceptualColorMode = 'auto' | 'palette' | 'gradient' | 'color_map';
export interface PerceptualGradientStop { t: number; color: string; }
export interface PerceptualColorPassOptions {
  steps?: number;
  dampening?: number;
  arcSteps?: number;
  targetDeltaE?: number;
  neutralAxis?: boolean;
}
export interface PerceptualColorPassInput {
  palette?: readonly string[];
  gradient?: readonly (string | PerceptualGradientStop)[];
  colorMap?: string | readonly (string | PerceptualGradientStop)[];
  steps?: number;
  dampening?: number;
  arcSteps?: number;
  targetDeltaE?: number;
  neutralAxis?: boolean;
  scientific?: boolean;
}
export interface PerceptualPaletteResult {
  colors: string[];
  pairwiseDeltaE: number[];
  minDeltaE: number;
  maxDeltaE: number;
  meanDeltaE: number;
  nearestNeutral?: string[];
}
export interface PerceptualGradientResult {
  stops: PerceptualGradientStop[];
  colors: string[];
  deltaE: number[];
  minDeltaE: number;
  maxDeltaE: number;
  meanDeltaE: number;
}
export interface PerceptualColorMapResult extends PerceptualGradientResult { name: string; }
export interface PerceptualColorPassResult {
  algorithm: 'perceptual_lerp_delta_e2000';
  source: PerceptualColorPassSource;
  scientific: boolean;
  targetDeltaE: number;
  dampening: number;
  palette?: PerceptualPaletteResult;
  gradient?: PerceptualGradientResult;
  colorMap?: PerceptualColorMapResult;
  warnings: string[];
}
export interface PerceptualColorAnalysis {
  color: string;
  lightness: number;
  chroma: number;
  hue: number;
  nearestNeutral: 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 PerceptualColorTraitOutput {
  mode: PerceptualColorMode;
  palette?: string[];
  gradient?: PerceptualGradientStop[];
  colorMap?: string;
  analysis?: PerceptualColorAnalysis[];
  compilerColorPass: PerceptualColorPassResult;
}
export interface PerceptualColorState {
  revisions: number;
  lastApplied: PerceptualColorTraitOutput | null;
}
export interface PerceptualColorCompilerMetadata {
  mapName: string;
  colors: string[];
  stops: PerceptualGradientStop[];
  minDeltaE: number;
  maxDeltaE: number;
  meanDeltaE: number;
  warnings: string[];
  pass: PerceptualColorPassResult;
}
export const SCIENTIFIC_COLOR_MAPS: Record<string, readonly string[]>;
export const perceptualColorHandler: TraitHandler<PerceptualColorConfig>;
export function normalizeHexColor(color: string): string;
export function hexToSrgb(color: string): readonly [number, number, number];
export function srgbToHex(rgb: readonly [number, number, number]): string;
export function buildPerceptualGradient(
  stops: readonly (string | PerceptualGradientStop)[],
  options?: PerceptualColorPassOptions
): PerceptualGradientResult;
export function buildPerceptualPalette(
  colors: readonly string[],
  options?: PerceptualColorPassOptions
): PerceptualPaletteResult;
export function analyzePerceptualColor(color: string): {
  color: string;
  lightness: number;
  chroma: number;
  hue: number;
  nearestNeutral: string;
};
export function applyPerceptualColorPass(input: PerceptualColorPassInput): PerceptualColorPassResult;

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

export interface ReconstructionManifest {
  version: '1.0.0';
  worldId: string;
  displayName: string;
  createdAt: string;
  frameCount: number;
  bounds: { min: [number, number, number]; max: [number, number, number] };
  replayHash: string;
  simulationContract: {
    kind: 'holomap.reconstruction.v1';
    replayFingerprint: string;
    holoScriptBuild: string;
  };
  [key: string]: unknown;
}

export function assertHoloMapManifestContract(m: ReconstructionManifest): void;

export const DOMAIN_SIMULATION_RECEIPT_SCHEMA: 'holoscript.domain-simulation-receipt.v0.1.0';
export type DomainSimulationReceiptSchema = typeof DOMAIN_SIMULATION_RECEIPT_SCHEMA;
export type DomainSimulationReceiptHashAlgorithm = 'fnv1a32';
export type DomainReceiptJson =
  | string
  | number
  | boolean
  | null
  | DomainReceiptJson[]
  | { [key: string]: DomainReceiptJson };
export interface DomainSimulationReceiptAcceptance {
  accepted: boolean;
  violations: Array<{ criterion: string; message: string }>;
}
export interface DomainSimulationReceiptInput {
  plugin: string;
  pluginVersion: string;
  runId: string;
  createdAt?: string;
  modelId?: string;
  solverConfig: {
    solverType: string;
    scale: string;
    [key: string]: DomainReceiptJson;
  };
  resultSummary: { [key: string]: DomainReceiptJson };
  acceptance: DomainSimulationReceiptAcceptance;
  cael?: {
    version?: 'cael.v1';
    event?: string;
    solverType?: string;
  };
  artifacts?: Array<{
    kind: string;
    path?: string;
    hash?: string;
  }>;
}
export interface DomainSimulationReceipt {
  schema: DomainSimulationReceiptSchema;
  plugin: string;
  pluginVersion: string;
  runId: string;
  createdAt: string;
  modelId?: string;
  solverConfig: {
    solverType: string;
    scale: string;
    [key: string]: DomainReceiptJson;
  };
  resultSummary: { [key: string]: DomainReceiptJson };
  cael: {
    version: 'cael.v1';
    event: string;
    solverType: string;
  };
  acceptance: DomainSimulationReceiptAcceptance;
  artifacts?: Array<{
    kind: string;
    path?: string;
    hash?: string;
  }>;
  payloadHash: string;
  hashAlgorithm: DomainSimulationReceiptHashAlgorithm;
}
export interface DomainSimulationReceiptVerification {
  valid: boolean;
  errors: string[];
}
export function buildDomainSimulationReceipt(input: DomainSimulationReceiptInput): DomainSimulationReceipt;
export function verifyDomainSimulationReceipt(receipt: DomainSimulationReceipt): DomainSimulationReceiptVerification;
export function stableDomainReceiptHash(payload: unknown): string;
export function canonicalizeDomainReceiptPayload(payload: unknown): string;

export const SCALE_BRIDGE_PROJECTION_SCHEMA: 'holoscript.scale-bridge.projection.v0.1.0';
export type ScaleBridgeProjectionSchema = typeof SCALE_BRIDGE_PROJECTION_SCHEMA;
export type ScaleBridgeJson =
  | string
  | number
  | boolean
  | null
  | ScaleBridgeJson[]
  | { [key: string]: ScaleBridgeJson };
export interface ScaleDescriptor {
  id: string;
  label?: string;
  granularity?: string;
  includePaths?: string[];
  excludePaths?: string[];
  collectionLimits?: Record<string, number>;
  collectionStride?: Record<string, number>;
  defaultStride?: number;
  metadata?: { [key: string]: ScaleBridgeJson };
}
export interface ScaleBridgeProvenanceEdge {
  type: 'scale_projection';
  hashAlgorithm: 'sha256';
  sourceStateHash: string;
  projectedStateHash: string;
  targetScaleId: string;
}
export interface ScaleBridgeProjection<TState extends ScaleBridgeJson = ScaleBridgeJson> {
  schema: ScaleBridgeProjectionSchema;
  targetScale: ScaleDescriptor;
  state: TState;
  provenance: {
    edge: ScaleBridgeProvenanceEdge;
    carriedReceipts: ScaleBridgeJson[];
  };
}
export class ScaleBridge {
  static project(sourceState: unknown, scaleDescriptor: ScaleDescriptor): ScaleBridgeProjection;
  static hashState(state: unknown): string;
}
export function canonicalizeScaleBridgeJson(value: unknown): string;

// ============================================================================
// PARSERS
// ============================================================================

export interface HSPlusParserOptions {
  sourceMap?: boolean;
  strict?: boolean;
  enableTypeScriptImports?: boolean;
  enableVRTraits?: boolean;
}
export class HoloScriptPlusParser {
  constructor(options?: HSPlusParserOptions);
  parse(source: string): HSPlusParseResult;
  parseExpression(source: string): any;
  parseStatement(source: string): any;
}
export interface AgentBrainSourceHeader {
  brainName: string;
  version?: string;
  targets: string[];
}
export interface PreparedAgentBrainSource {
  header: AgentBrainSourceHeader;
  source: string;
  locationMap: Array<{ authoredLine: number; columnOffset: number }>;
}
export function preprocessAgentBrainSource(source: string): PreparedAgentBrainSource;

export interface ParseCacheStats {
  size: number;
  evictions: number;
  maxEntries: number;
}

export interface ParseCache {
  get(id: string, currentHash: string): any | null;
  set(id: string, hash: string, node: any): void;
  clear(): void;
  getStats(): ParseCacheStats;
}

export const globalParseCache: ParseCache;

export interface IncrementalParseResult {
  ast: any;
  cached: number;
  parsed: number;
  duration: number;
  changedChunks: string[];
}

export class ChunkBasedIncrementalParser {
  constructor(cache?: ParseCache);
  parse(source: string): IncrementalParseResult;
  clearCache(): void;
  getCacheStats(): ParseCacheStats;
}

export class HSPlusRuntime {
  constructor(options?: any);
  mount(container: any): void;
  unmount(): void;
  update(delta: number): void;
  setState(updates: Record<string, any>): void;
  getState(): Record<string, any>;
  on(event: string, handler: (payload: any) => void): () => void;
  emit(event: string, payload?: any): void;
}

export class World {
  constructor();
  createEntity(): string;
  removeEntity(id: string): void;
}

export class ComponentRegistry {
  static register(name: string, component: any): void;
}

export class HoloCompositionParser {
  parse(source: string): any;
}

export type CanonicalSourceSurface = 'holo' | 'hsplus' | 'hs';
export type CanonicalValidator = 'holo-parser' | 'typescript-hsplus' | 'rust-wasm';
export interface CanonicalDiagnostic {
  severity: 'error' | 'warning';
  message: string;
  line?: number;
  column?: number;
  code?: string;
  suggestion?: string;
}
export interface CanonicalSourceValidationRequest {
  source: string;
  fileName?: string;
  surface?: CanonicalSourceSurface | '.holo' | '.hsplus' | '.hs';
}
export type CanonicalHsDetailedValidator = (source: string) => string | unknown;
export interface CanonicalSourceValidationDependencies {
  validateHsDetailed?: CanonicalHsDetailedValidator;
}
export interface CanonicalSourceValidationResult {
  valid: boolean;
  surface: CanonicalSourceSurface;
  validator: CanonicalValidator;
  errors: CanonicalDiagnostic[];
  warnings: CanonicalDiagnostic[];
  ast?: unknown;
  preprocessedAgentBrain?: boolean;
  agentBrainHeader?: {
    brainName: string;
    version?: string;
    targets: string[];
  };
}
export function resolveCanonicalSourceSurface(request: {
  fileName?: string;
  surface?: CanonicalSourceSurface | '.holo' | '.hsplus' | '.hs';
}): CanonicalSourceSurface;
export function validateCanonicalSource(
  request: CanonicalSourceValidationRequest,
  dependencies?: CanonicalSourceValidationDependencies
): CanonicalSourceValidationResult;

export class HoloScriptCodeParser {
  parse(source: string): ParseResult;
  parseExpression(source: string): any;
  parseBlock(source: string): any[];
  getErrors(): any[];
}

export function parse(source: string, options?: any): ParseResult;
export function parseHolo(source: string, options?: any): any;
export function parseHoloStrict(source: string): any;
export function parseHoloScriptPlus(
  source: string,
  options?: HSPlusParserOptions
): HSPlusParseResult;
export const holoFactory: any;
export function generateHoloSource(ast: any): string;

// uAAL cognitive front-end bridge (G3): HoloComposition behavior -> UAAL bytecode.
export class UaalBehaviorCompiler {
  compile(
    composition: any,
    options?: {
      sourceSurface?: '.holo' | '.hsplus';
      entryPoints?: string[];
    }
  ): {
    bytecode: { version: number; instructions: Array<{ opCode: number; operands?: any[] }> };
    stats: {
      actions: number;
      handlers: number;
      statements: number;
      instructions: number;
      executeCalls: number;
      branches: number;
      unhandled: Record<string, number>;
      compilationMs: number;
    };
    semanticClosure: any;
  };
}
export interface UaalBehaviorStateReference {
  abi: 'holo.behavior.state-ref.v1';
  key: string;
}
export function resolveUaalBehaviorOperand(
  operand: any,
  context: Readonly<Record<string, any>>
): any;

// ============================================================================
// COMPOSITION TYPES (from .holo files)
// ============================================================================

export interface HoloComposition extends ASTNode {
  type: 'Composition';
  name: string;
  environment?: any;
  state?: any;
  templates: any[];
  objects: any[];
  spatialGroups: any[];
  lights: any[];
  effects?: any;
  camera?: any;
  logic?: any;
  imports: any[];
  timelines: any[];
  audio: any[];
  zones: any[];
  ui?: any;
  transitions: any[];
  conditionals: any[];
  iterators: any[];
  [key: string]: any;
}

export interface HoloEnvironment extends ASTNode {
  type: 'Environment';
  properties: any[];
}

export interface HoloState extends ASTNode {
  type: 'State';
  properties: any[];
}

export interface HoloTemplate extends ASTNode {
  type: 'Template';
  name: string;
  properties: any[];
}

export interface HoloObjectDecl extends ASTNode {
  type: 'Object';
  name: string;
  traits: any[];
  properties: any[];
}

export interface HoloObjectTrait extends ASTNode {
  type: 'Trait';
  name: string;
  config?: any;
  args?: any[];
  platformConstraint?: PlatformConstraint;
}

export interface HoloSpatialGroup extends ASTNode {
  type: 'SpatialGroup';
  name: string;
  objects: HoloObjectDecl[];
}

export interface HoloLight extends ASTNode {
  type: 'Light';
}

export interface HoloLogic extends ASTNode {
  type: 'Logic';
}

export interface HoloEventHandler extends ASTNode {
  event: string;
  [key: string]: any;
}

export interface HoloAction extends ASTNode {
  name: string;
  [key: string]: any;
}

export interface HoloStatement extends ASTNode {
  [key: string]: any;
}

export interface HoloParseResult {
  success: boolean;
  ast?: HoloComposition;
  errors: any[];
  warnings: any[];
}

export type HoloContainmentPerceptionErrorCode =
  | 'invalid-source'
  | 'unsupported-import'
  | 'unsupported-template'
  | 'unsupported-dynamic-containment'
  | 'unsupported-platform-constraint'
  | 'duplicate-semantic-id'
  | 'invalid-semantic-property'
  | 'conflicting-semantic-property'
  | 'unknown-query-entity';

export class HoloContainmentPerceptionError extends Error {
  readonly code: HoloContainmentPerceptionErrorCode;
  constructor(code: HoloContainmentPerceptionErrorCode, message: string);
}

export interface HoloContainmentPerceptionOptions {
  sourceId?: string;
  query?: UAALContainmentQuery;
}

export interface HoloContainmentSourceRef {
  format: '.holo';
  parser: 'HoloCompositionParser';
  composition: string;
  sourceDigest: string;
  sourceId?: string;
  path: string;
  line?: number;
  column?: number;
}

export interface HoloContainmentPerceptionMetadata {
  format: '.holo';
  parser: 'HoloCompositionParser';
  composition: string;
  sourceDigest: string;
  sourceId?: string;
}

export type HoloPerceivedSemanticEntity = UAALSemanticEntity & {
  source: HoloContainmentSourceRef;
};

export type HoloPerceivedContainmentRelation = UAALContainmentRelation & {
  source: HoloContainmentSourceRef;
};

export type HoloPerceivedContainmentIR = UAALContainmentIR & {
  entities: HoloPerceivedSemanticEntity[];
  containment: HoloPerceivedContainmentRelation[];
  perception: HoloContainmentPerceptionMetadata;
};

export function perceiveContainmentIR(
  source: string,
  options?: HoloContainmentPerceptionOptions
): HoloPerceivedContainmentIR;

export type HSPlusStructMeaningLoweringErrorCode =
  | 'invalid-source'
  | 'invalid-struct'
  | 'duplicate-struct';

export class HSPlusStructMeaningLoweringError extends Error {
  readonly code: HSPlusStructMeaningLoweringErrorCode;
  constructor(code: HSPlusStructMeaningLoweringErrorCode, message: string);
}

export interface HSPlusStructMeaningLoweringOptions {
  sourceId?: string;
}

export interface HSPlusUnknownStructSource {
  line?: number;
  column?: number;
}

export interface HSPlusUnknownStructMeaning {
  name: string;
  unknownFields: UnknownFieldLowering[];
  source: HSPlusUnknownStructSource;
}

export interface HSPlusUnknownStructMeaningProjection {
  schema: 'holoscript.hsplus-unknown-struct-meaning.v1';
  format: '.hsplus';
  parser: 'HoloScriptPlusParser';
  sourceDigest: string;
  sourceId?: string;
  structs: HSPlusUnknownStructMeaning[];
}

export function lowerHSPlusUnknownStructsToMeaning(
  source: string,
  options?: HSPlusStructMeaningLoweringOptions
): HSPlusUnknownStructMeaningProjection;

// ============================================================================
// TRAIT VISUAL SYSTEM
// ============================================================================

export class TraitCompositor {
  compose(traits: any[], material: any): any;
  [key: string]: any;
}

export interface TraitVisualConfig {
  [key: string]: any;
}

export interface R3FMaterialProps {
  [key: string]: any;
}

export type AssetMaturity = 'draft' | 'mesh' | 'final';

export interface R3FNode {
  type: string;
  id?: string;
  props: Record<string, any>;
  children?: R3FNode[];
  traits?: Map<string, any>;
  directives?: any[];
  assetMaturity?: AssetMaturity;
  [key: string]: any;
}

export interface VisualLayer {
  [key: string]: any;
}

export const VISUAL_LAYER_PRIORITY: Record<string, number>;
export const MATERIAL_PRESETS: Record<string, any>;
export const ENVIRONMENT_PRESETS: Record<string, any>;

// ============================================================================
// MATERIAL SYSTEM
// ============================================================================

export interface MaterialConfig {
  [key: string]: any;
}

export interface PBRMaterial {
  [key: string]: any;
}

export type MaterialType = string;
export type TextureChannel = string;

export type HoloMaterialType = 'material' | 'pbr_material' | 'unlit_material' | 'shader' | 'toon_material' | 'glass_material' | 'subsurface_material' | string;

export interface TextureMapDef {
  channel: TextureChannel;
  source: string;
  tiling?: [number, number];
  filtering?: 'nearest' | 'linear' | 'trilinear';
  strength?: number;
  intensity?: number;
  scale?: number;
  format?: string;
  channelSelect?: 'r' | 'g' | 'b' | 'a';
}

export interface ShaderPassDef {
  name?: string;
  vertex?: string;
  fragment?: string;
  blend?: string;
  properties?: Record<string, unknown>;
}

export interface MaterialDefinition {
  type: HoloMaterialType;
  name: string;
  traits: string[];
  baseColor?: string | number[];
  roughness?: number;
  metallic?: number;
  emissive?: string;
  emissiveIntensity?: number;
  opacity?: number;
  IOR?: number;
  transmission?: number;
  thickness?: number;
  doubleSided?: boolean;
  textureMaps: TextureMapDef[];
  shaderPasses: ShaderPassDef[];
  shaderConnections: Array<{ output: string; input: string }>;
  properties: Record<string, unknown>;
  [key: string]: any;
}

export interface CompositionMaterialNode {
  type: string;
  name: string;
  traits?: Array<{ name: string; arguments?: unknown[] }>;
  properties?: Record<string, unknown>;
  textureMaps?: Array<{ channel: string; source?: string; properties?: Record<string, unknown> }>;
  shaderPasses?: Array<{ name?: string; properties?: Record<string, unknown> }>;
  shaderConnections?: Array<{ output: string; input: string }>;
  children?: CompositionMaterialNode[];
}

export class HoloScriptMaterialParser {
  static parseAll(rootNode: ASTNode): MaterialDefinition[];
  static parseFromComposition(nodes: CompositionMaterialNode[]): MaterialDefinition[];
  static parse(node: ASTNode): MaterialDefinition;
  static parseJSON(json: Record<string, unknown>): MaterialDefinition;
}

export interface TextureMap {
  [key: string]: any;
}

export class MaterialTrait {
  constructor(config: any);
  toR3F(): Record<string, any>;
  [key: string]: any;
}
export function createMaterialTrait(config: any): MaterialTrait;

export class LightingTrait {
  constructor(config: any);
  [key: string]: any;
}
export function createLightingTrait(config: any): LightingTrait;
export const LIGHTING_PRESETS: Record<string, any>;

export class RenderingTrait {
  constructor(config: any);
  [key: string]: any;
}
export function createRenderingTrait(config: any): RenderingTrait;

// ============================================================================
// SHADER SYSTEM
// ============================================================================

export type ShaderType = 'vertex' | 'fragment' | 'compute';
export type UniformType = 'float' | 'vec2' | 'vec3' | 'vec4' | 'mat3' | 'mat4' | 'sampler2D' | 'int' | 'bool';

export interface UniformDefinition {
  type: UniformType;
  value: any;
  [key: string]: any;
}

export interface ShaderConfig {
  vertexShader?: string;
  fragmentShader?: string;
  uniforms?: Record<string, UniformDefinition>;
  transparent?: boolean;
  depthTest?: boolean;
  depthWrite?: boolean;
  side?: number;
  [key: string]: any;
}

export class ShaderTrait {
  constructor(config: any);
  toThreeJSConfig(): ShaderConfig;
  [key: string]: any;
}
export function createShaderTrait(config: any): ShaderTrait;
export const SHADER_PRESETS: Record<string, any>;
export const SHADER_CHUNKS: Record<string, string>;

// ============================================================================
// PROCEDURAL GEOMETRY
// ============================================================================

export interface GeometryData {
  vertices: Float32Array;
  normals: Float32Array;
  indices: Uint32Array;
  uvs?: Float32Array;
}

export interface BlobDef {
  center: [number, number, number];
  radius: number;
  strength?: number;
}

export function generateSplineGeometry(
  points: Array<[number, number, number]>,
  radius?: number,
  segments?: number,
  radialSegments?: number
): GeometryData;

export function generateHullGeometry(
  blobs: BlobDef[],
  resolution?: number,
  isoLevel?: number
): GeometryData;

export function generateMembraneGeometry(
  profiles: Array<Array<[number, number, number]>>,
  segments?: number
): GeometryData;

// ============================================================================
// GLTF PIPELINE
// ============================================================================

export interface GLTFPipelineOptions {
  format?: 'glb' | 'gltf';
  dracoCompression?: boolean;
  quantize?: boolean;
  prune?: boolean;
  dedupe?: boolean;
  embedTextures?: boolean;
  generator?: string;
  copyright?: string;
}

export interface GLTFExportResult {
  binary?: Uint8Array;
  json?: object;
  buffer?: Uint8Array;
  stats: GLTFExportStats;
}

export interface GLTFExportStats {
  meshCount: number;
  materialCount: number;
  textureCount: number;
  animationCount: number;
  fileSize: number;
  [key: string]: any;
}

export class GLTFPipeline {
  constructor(options?: GLTFPipelineOptions);
  export(composition: any): Promise<GLTFExportResult>;
  [key: string]: any;
}
export function createGLTFPipeline(options?: GLTFPipelineOptions): GLTFPipeline;

/** Generate hexagonal scale texture (RGBA Uint8Array) */
export function generateScaleTexture(size: number, baseColor?: [number, number, number]): Uint8Array;
/** Generate tangent-space normal map for hexagonal scales (RGBA Uint8Array) */
export function generateScaleNormalMap(size: number): Uint8Array;

// ============================================================================
// COMPRESSION & SPLATTING
// ============================================================================

export interface CompressionOptions {
  method?: 'lz4' | 'zstd' | 'brotli';
  level?: number;
  [key: string]: any;
}

export class AdvancedCompression {
  constructor(options?: any);
  static compressBuffer(buffer: ArrayBuffer | Uint8Array, options?: CompressionOptions): Promise<Uint8Array>;
  static decompressBuffer(buffer: Uint8Array, method?: string): Promise<ArrayBuffer>;
  [key: string]: any;
}

export interface INeuralSplatPacket {
  frameId: number;
  cameraState: {
    viewProjectionMatrix: number[];
    cameraPosition: number[];
  };
  splatCount: number;
  compressedSplatsBuffer: ArrayBuffer;
  sortedIndicesBuffer: ArrayBuffer;
}

// ============================================================================
// USDZ PIPELINE (USDA/USDZ Export)
// ============================================================================

export interface USDZPipelineOptions {
  upAxis?: 'Y' | 'Z';
  metersPerUnit?: number;
  includeAnimations?: boolean;
  exportMaterials?: boolean;
  defaultMaterial?: string;
  textureData?: Record<string, Uint8Array>;
}

export interface USDMaterial {
  name: string;
  baseColor?: [number, number, number];
  metallic?: number;
  roughness?: number;
  emissiveColor?: [number, number, number];
  emissiveIntensity?: number;
  opacity?: number;
  ior?: number;
  clearcoat?: number;
  clearcoatRoughness?: number;
  transmission?: number;
  thickness?: number;
  attenuationColor?: [number, number, number];
  attenuationDistance?: number;
  sheen?: number;
  sheenRoughness?: number;
  sheenColor?: [number, number, number];
  iridescence?: number;
  iridescenceIOR?: number;
  anisotropy?: number;
  anisotropyRotation?: number;
  textureMaps?: Record<string, string>;
}

export interface USDGeometry {
  type: 'sphere' | 'cube' | 'cylinder' | 'cone' | 'plane' | 'mesh';
  radius?: number;
  size?: [number, number, number];
  height?: number;
  points?: number[][];
  faceVertexCounts?: number[];
  faceVertexIndices?: number[];
}

export interface USDXform {
  name: string;
  translation?: [number, number, number];
  rotation?: [number, number, number];
  scale?: [number, number, number];
  geometry?: USDGeometry;
  material?: string;
  children?: USDXform[];
}

export interface USDADocument {
  header: string;
  stage: string;
  materials: string;
  prims: string;
}

export class USDZPipeline {
  constructor(options?: USDZPipelineOptions);
  generateUSDA(composition: HoloComposition): string;
  generateUSDZ(composition: HoloComposition): Uint8Array;
}

export function generateUSDA(composition: HoloComposition, options?: USDZPipelineOptions): string;
export function generateUSDZ(composition: HoloComposition, options?: USDZPipelineOptions): Uint8Array;
export function getUSDZConversionCommand(usdaPath: string, usdzPath: string): string;
export function getPythonConversionScript(usdaPath: string, usdzPath: string): string;

// ============================================================================
// USD PHYSICS COMPILER (Isaac Sim / Omniverse)
// ============================================================================

export interface USDPhysicsCompilerOptions {
  stageName?: string;
  upAxis?: 'Y' | 'Z';
  metersPerUnit?: number;
  timeCodesPerSecond?: number;
  includePhysicsScene?: boolean;
  gravity?: [number, number, number];
  physicsTimestep?: number;
  enableGPUDynamics?: boolean;
  includeCollision?: boolean;
  includeVisual?: boolean;
  defaultMass?: number;
  defaultStaticFriction?: number;
  defaultDynamicFriction?: number;
  defaultRestitution?: number;
  enableArticulation?: boolean;
}

export class USDPhysicsCompiler {
  constructor(options?: USDPhysicsCompilerOptions);
  compile(composition: HoloComposition, agentToken: string, outputPath?: string): string;
}

export function compileToUSDPhysics(composition: HoloComposition, options?: USDPhysicsCompilerOptions): string;
export function compileForIsaacSim(composition: HoloComposition, options?: Partial<USDPhysicsCompilerOptions>): string;

// ============================================================================
// ============================================================================
// REACTIVE STATE & EVENTS
// ============================================================================

export class ExpressionEvaluator {
  constructor(context?: Record<string, unknown>, builtins?: Record<string, unknown>);
  evaluate(expression: string, context?: any): any;
  extractVariables(expression: string): string[];
  updateContext(updates: Record<string, unknown>): void;
}

export class EventBus {
  constructor();
  on(event: string, callback: (data: unknown) => void, priority?: number): number;
  once(event: string, callback: (data: unknown) => void, priority?: number): number;
  off(listenerId: number): void;
  offAll(event: string): void;
  emit(event: string, data?: unknown): void;
  getHistory(): Array<{ event: string; data: unknown; timestamp: number }>;
  listenerCount(event: string): number;
  setPaused(paused: boolean): void;
  clear(): void;
}
export const eventBus: EventBus;
export function getSharedEventBus(): EventBus;
export function setSharedEventBus(bus: EventBus): void;

// COMPILERS & GENERATORS
// ============================================================================

export interface BaseCompilerOptions {
  generateDocs?: boolean;
  docsOptions?: any;
  [key: string]: any;
}

export class CompilerBase {
  protected compilerName: string;
  validateCompilerAccess(agentToken: string, outputPath?: string): void;
  generateDocumentation(composition: any, code: string, options?: any): any;
  compile(composition: any, agentToken: string, outputPath?: string, options?: BaseCompilerOptions): any;
  [key: string]: any;
}

export class SemanticSceneGraph {
  static generate(composition: any, options?: any): string;
  static generateObject(composition: any, options?: any): any;
  [key: string]: any;
}

export class HoloScriptCompiler {
  compile(ast: any, target: string): any;
}

export interface SceneIRCompilerOptions {
  qualityTier?: 'low' | 'med' | 'high' | 'ultra';
  defaultLighting?: boolean;
  holomapPointCloud?: any;
  platformTarget?: any;
}

export class SceneIRCompiler {
  constructor(options?: SceneIRCompilerOptions);
  compile(ast: any): any;
  compileComposition(composition: any): R3FNode;
  [key: string]: any;
}

export interface SceneIRTsxEmitterOptions {
  componentName?: string;
  sourcePath?: string;
  includeCanvas?: boolean;
}

export function emitSceneIRTsx(root: R3FNode, options?: SceneIRTsxEmitterOptions): string;

export interface CompilationResult {
  success: boolean;
  sceneIR?: unknown;
  error?: string;
  metadata?: {
    zones: number;
    entities: number;
    handlers: number;
    duration: number;
  };
}

export class CompilerBridge {
  compile(holoScript: string): Promise<CompilationResult>;
  validate(holoScript: string): Promise<{ valid: boolean; errors: string[] }>;
  getMetrics(holoScript: string): { lines: number; characters: number; estimatedZones: number; estimatedComplexity: 'simple' | 'moderate' | 'complex' };
}

export function getCompilerBridge(): CompilerBridge;

export interface TraitCompositionDecl {
  name: string;
  components: string[];
  overrides?: Record<string, unknown>;
}

export interface ComposedTraitDef {
  name: string;
  components: string[];
  defaultConfig: Record<string, unknown>;
}

export interface ComponentTraitHandler {
  defaultConfig?: Record<string, unknown>;
  conflicts?: string[];
}

export class TraitDependencyGraph {
  constructor(options?: any);
  registerTrait(name: string, handler: any): void;
  [key: string]: any;
}

export class TraitCompositionCompiler {
  constructor(inheritanceResolver?: any);
  setInheritanceResolver(resolver: any): void;
  compile(decls: TraitCompositionDecl[], getHandler: (name: string) => ComponentTraitHandler | undefined, traitGraph?: any, agentToken?: string): ComposedTraitDef[];
}

// ============================================================================
// RUNTIME & EXECUTION
// ============================================================================

export type HoloValue = any;
export interface HoloTemplate {
  type: string;
  id: string;
  [key: string]: any;
}
export interface HSPlusForDirective {
  type: 'for';
  variable: string;
  range?: [number, number];
  iterable?: string;
  body: unknown[];
}
export interface RaycastHit {
  point: Vector3;
  normal: Vector3;
  distance: number;
  bodyId: string;
  [key: string]: any;
}

export class HoloScriptRuntime {
  constructor(importLoader?: any, customFunctions?: any);
  execute(ast: any, context?: any): Promise<any>;
  executeProgram(nodes: any[], depth?: number): Promise<any[]>;
  executeHoloProgram(statements: any[], scopeOverride?: any): Promise<any[]>;
  getContext(): any;
  reset(): void;
  startVisualizationServer(port?: number): void;
  broadcast(type: string, payload: unknown): void;
  on(event: string, handler: (...args: any[]) => any): void;
  off(event: string, handler?: (...args: any[]) => any): void;
  emit(event: string, data?: unknown): Promise<void>;
  setVariable(name: string, value: any, scopeOverride?: any): void;
  getVariable(name: string, scopeOverride?: any): any;
  callFunction(name: string, args?: any[]): Promise<any>;
  registerFunction(name: string, handler: (...args: any[]) => any): void;
  registerTrait(name: string, handler: any): void;
  getState(): Record<string, any>;
  getRootScope(): any;
  getExecutionHistory(): any[];
  getCallStack(): string[];
  [key: string]: any;
}

export interface RuntimeOptions {
  [key: string]: any;
}

export interface Renderer {
  [key: string]: any;
}

export interface NodeInstance {
  [key: string]: any;
}

export type HoloScriptValue = string | number | boolean | null | HoloScriptValue[] | { [key: string]: HoloScriptValue };

export interface ExecutionResult {
  success: boolean;
  result?: any;
  error?: string;
  duration?: number;
  memoryUsed?: number;
  executionTime?: number;
  hologram?: { shape?: string; color?: string; [key: string]: any };
  spatialPosition?: { x: number; y: number; z: number; [key: string]: any };
  output?: any;
}

export interface SpatialPosition {
  x: number;
  y: number;
  z: number;
  rotation?: { x: number; y: number; z: number; w?: number };
  scale?: { x: number; y: number; z: number };
}

export interface HSPlusAST {
  type: 'Program';
  body: any[];
  version: string | number;
  root: any;
  imports: Array<{ path: string; alias: string; namedImports?: string[]; isWildcard?: boolean }>;
  hasState: boolean;
  hasVRTraits: boolean;
  hasControlFlow: boolean;
  migrations?: any[];
  nodes?: HSPlusASTNode[];
  metadata?: Record<string, any>;
}

export interface OrbNode extends ASTNode {
  type: 'Orb';
  name: string;
  properties: Record<string, any>;
  traits?: string[];
}

export class HoloScriptPlusRuntimeImpl {
  constructor(options?: RuntimeOptions);
  execute(ast: any, context?: any): Promise<ExecutionResult>;
  createRenderer(config?: any): Renderer;
  getState(): Record<string, any>;
  setState(updates: Record<string, any>): void;
  dispose(): void;
}

export function createRuntime(options?: RuntimeOptions): HoloScriptPlusRuntimeImpl;

// ============================================================================
// TYPE CHECKING
// ============================================================================

export class HoloScriptTypeChecker {
  check(ast: any): any;
  getType(node: any): any;
}

export interface ValidationError {
  message: string;
  loc?: any;
}

// ============================================================================
// ERROR HANDLING & DIAGNOSTICS
// ============================================================================

export interface RichParseError {
  message: string;
  loc?: any;
  code?: string;
  suggestion?: string;
  severity?: 'error' | 'warning';
}

export const HSPLUS_ERROR_CODES: Record<string, string>;

export function createRichError(message: string, code?: string): RichParseError;
export function createTraitError(traitName: string): RichParseError;
export function createKeywordError(keyword: string): RichParseError;
export function findSimilarTrait(partialName: string): string | null;
export function findSimilarKeyword(partialName: string): string | null;
export function getSourceContext(source: string, location: any): string;
export function formatRichError(error: RichParseError): string;
export function formatRichErrors(errors: RichParseError[]): string;
export function getErrorCodeDocumentation(code: string): string;

// ============================================================================
// DEBUGGER
// ============================================================================

export class HoloScriptDebugger {
  debug(ast: any): any;
  on(event: string, callback: any): void;
  start(): void;
  stop(): void;
  loadSource(source: string, path?: string): { success: boolean; errors?: string[] };
  clearBreakpoints(): void;
  setBreakpoint(line: number, options?: Partial<Breakpoint>): any;
  continue(): void;
  stepOver(): void;
  stepInto(): void;
  stepOut(): void;
  pause(): void;
  getCallStack(): any[];
  getState(): any;
  getRuntime(): any;
  evaluate(expression: string, frameId?: number): any;
  getVariables(frameId?: number): any;
}

// ============================================================================
// SAFETY & EFFECTS
// ============================================================================

export interface EffectASTNode {
  [key: string]: any;
}

export interface SafetyReport {
  [key: string]: any;
}

export type SafetyVerdict = 'safe' | 'warnings' | 'unsafe' | 'unchecked';
export type VREffect = string;
export type EffectCategory = string;
export type EffectViolationSeverity = 'error' | 'warning' | 'info';
export interface EffectViolation { effect: VREffect; severity: EffectViolationSeverity; [key: string]: any; }
export interface EffectDeclaration { effects: VREffect[]; [key: string]: any; }

// ============================================================================
// PLATFORM TYPES
// ============================================================================

export type XRPlatformTarget = string;
export type XRPlatformCategory = string;

export interface XRPlatformCapabilities {
  [key: string]: any;
}

// ============================================================================
// LSP & SAFETY TYPES
// ============================================================================

export interface StackFrame {
  id: number;
  name: string;
  file?: string;
  line: number;
  column: number;
  variables: Map<string, unknown>;
  node: any;
}

export interface Breakpoint {
  id: string;
  line: number;
  column?: number;
  condition?: string;
  hitCount: number;
  enabled: boolean;
  file?: string;
}

export interface SafetyPassConfig { [key: string]: any; }
export interface SafetyPassResult { [key: string]: any; }
export interface EffectViolation { [key: string]: any; }
export interface BudgetDiagnostic { [key: string]: any; }
export interface CapabilityRequirement { [key: string]: any; }
export interface LinearViolation { [key: string]: any; }
export type HSPlusStructField =
  | {
      name: string;
      projection: 'typed';
      type: string;
      annotations?: string[];
      optional?: true;
      defaultSource?: string;
    }
  | {
      name: string;
      projection: 'preserved-opaque';
      optional?: true;
      type?: never;
      annotations?: never;
      defaultSource?: never;
    };
export interface ASTProgram {
  type: 'Program';
  children: HSPlusNode[];
  body: HSPlusNode[];
  version: string | number;
  root: HSPlusNode;
  imports: Array<{
    path: string;
    alias: string;
    namedImports?: string[];
    isWildcard?: boolean;
  }>;
  hasState: boolean;
  hasVRTraits: boolean;
  hasControlFlow: boolean;
  migrations?: unknown[];
  [key: string]: unknown;
}
export type HSPlusASTNode = HSPlusNode;
export interface HSPlusCompileResult {
  success: boolean;
  code?: string;
  sourceMap?: unknown;
  errors: Array<{ message: string; line: number; column: number }>;
  ast?: ASTProgram;
  compiledExpressions?: unknown;
  requiredCompanions?: string[];
  features?: unknown;
  warnings?: unknown[];
  [key: string]: unknown;
}
export interface HSPlusParseResult extends HSPlusCompileResult {
  ast: ASTProgram;
}

export function runSafetyPass(ast: any, config?: SafetyPassConfig): SafetyPassResult;

export class HoloScriptValidator {
  validate(ast: any): ValidationError[];
}

export function createTypeChecker(): HoloScriptTypeChecker;

export interface AIAdapter { [key: string]: any; }
export function getDefaultAIAdapter(): AIAdapter;
export function useGemini(config?: any): AIAdapter;
export function useOllama(config?: any): AIAdapter;
export class SemanticSearchService<T = any> { 
  constructor(adapter: AIAdapter, items: T[]);
  initialize(): Promise<void>;
  search(query: string, limit?: number): Promise<any[]>;
}

// ============================================================================
// VR TRAIT SYSTEM TYPES
// ============================================================================

// Vector3 is a tuple in source (packages/core/src/types/HoloScriptPlus.ts:10).
// Emitting as {x,y,z} interface here in 2026-04-22..04-25 produced hundreds
// of engine-package TS errors like "Type 'number[]' is missing properties
// x,y,z from Vector3" because consumer code correctly uses tuple-form
// (engine/src/animation/IKSolver.ts:139, etc). Restoring tuple form here
// lets pre-flight pass; for {x,y,z} object shape use three.Vector3 directly.
export type Vector3 = [number, number, number];

export interface VRHand {
  id: string;
  position: Vector3;
  rotation: Quaternion;
  velocity: Vector3;
  joints?: Map<string, { position: Vector3; rotation: Vector3 }>;
  pinch?: number;
  pinchStrength?: number;
  grip: number;
  gripStrength?: number;
  trigger: number;
  pointing?: boolean;
}

export interface VRContext {
  hands: { left: VRHand | null; right: VRHand | null };
  headset: { position: Vector3; rotation: Vector3 };
  getPointerRay(hand: 'left' | 'right'): { origin: Vector3; direction: Vector3 } | null;
  getDominantHand(): VRHand | null;
}

export interface PhysicsContext {
  applyVelocity(node: HSPlusNode, velocity: Vector3): void;
  applyAngularVelocity(node: HSPlusNode, angularVelocity: Vector3): void;
  setKinematic(node: HSPlusNode, kinematic: boolean): void;
  raycast(origin: Vector3, direction: Vector3, maxDistance: number): RaycastHit | null;
  getBodyPosition(nodeId: string): Vector3 | null;
  getBodyVelocity(nodeId: string): Vector3 | null;
}

export interface AudioContext {
  playSound(source: string, options?: { position?: Vector3; volume?: number; spatial?: boolean }): void;
  updateSpatialSource?(nodeId: string, options: Record<string, any>): void;
  registerAmbisonicSource?(nodeId: string, order: number): void;
  setAudioPortal?(portalId: string, targetZone: string, openingSize: number): void;
  updateAudioMaterial?(nodeId: string, absorption: number, reflection: number): void;
}

export interface HapticsContext {
  pulse(hand: 'left' | 'right', intensity: number, duration?: number): void;
  rumble(hand: 'left' | 'right', intensity: number): void;
}

export interface AccessibilityContext {
  announce(text: string): void;
  setScreenReaderFocus(nodeId: string): void;
  setAltText(nodeId: string, text: string): void;
  setHighContrast(enabled: boolean): void;
}

export type ARTrackingState = 'not_available' | 'limited' | 'normal' | 'lost';

export interface ARSessionPose {
  anchorId?: string;
  target?: string;
  position: Vector3;
  rotation?: Vector3;
  confidence?: number;
  timestampMs?: number;
  trackingState?: ARTrackingState;
  source?: string;
}

export interface ARSessionContext {
  readonly available: boolean;
  getPose(nodeId?: string): ARSessionPose | null;
  getAnchor?(anchorId: string): ARSessionPose | null;
}

export interface TraitContext {
  vr: VRContext;
  physics: PhysicsContext;
  audio: AudioContext;
  haptics: HapticsContext;
  accessibility?: AccessibilityContext;
  arSession?: ARSessionContext;
  emit(event: string, payload?: unknown): void;
  getState(): Record<string, unknown>;
  setState(updates: Record<string, unknown>): void;
  getScaleMultiplier(): number;
  setScaleContext(magnitude: string): void;
}

export type TraitEvent =
  | { type: 'xr:grab'; hand: 'left' | 'right'; [key: string]: any }
  | { type: 'xr:release'; hand: 'left' | 'right'; [key: string]: any }
  | { type: 'collision'; other: string; [key: string]: any }
  | { type: string; [key: string]: any };

export interface HSPlusNode extends ASTNode {
  id?: string;
  name?: string;
  nameOrigin?: 'explicit' | 'synthetic';
  traits?: Map<string, unknown>;
  children?: HSPlusNode[];
  body?: unknown;
  fields?: HSPlusStructField[];
  [key: string]: any;
}

export interface TraitBehavior {
  readonly traitId: string;
  readonly name: string;
  enabled: boolean;
  initialize?(): void | Promise<void>;
  update?(deltaTime: number): void;
  dispose?(): void | Promise<void>;
}

export class ProceduralSkill {
  id: string;
  name: string;
  category: string;
  description: string;
  constructor(config: { id: string; name: string; category: string; description: string });
  execute(input: unknown): unknown;
}

export type VRTraitName = string;

export class VRTraitRegistry {
  register(handler: TraitHandler): void;
  getHandler(name: VRTraitName): TraitHandler | undefined;
  attachTrait(node: HSPlusNode, traitName: VRTraitName, config: unknown, context: TraitContext): void;
  detachTrait(node: HSPlusNode, traitName: VRTraitName, context: TraitContext): void;
  updateAllTraits(node: HSPlusNode, context: TraitContext, delta: number): void;
  handleEventForAllTraits(node: HSPlusNode, context: TraitContext, event: TraitEvent): void;
}

export declare const vrTraitRegistry: VRTraitRegistry;

// ============================================================================
// TRAIT CONTEXT FACTORY (migrated from Hololand)
// ============================================================================

export interface PhysicsProvider {
  applyVelocity(nodeId: string, velocity: Vector3): void;
  applyAngularVelocity(nodeId: string, angularVelocity: Vector3): void;
  setKinematic(nodeId: string, kinematic: boolean): void;
  raycast(origin: Vector3, direction: Vector3, maxDistance: number): RaycastHit | null;
}

export interface AudioProvider {
  playSound(source: string, options?: { position?: Vector3; volume?: number; spatial?: boolean }): void;
  updateSpatialSource?(nodeId: string, options: Record<string, any>): void;
  registerAmbisonicSource?(nodeId: string, order: number): void;
  setAudioPortal?(portalId: string, targetZone: string, openingSize: number): void;
  updateAudioMaterial?(nodeId: string, absorption: number, reflection: number): void;
}

export interface HapticsProvider {
  pulse(hand: 'left' | 'right', intensity: number, duration?: number): void;
  rumble(hand: 'left' | 'right', intensity: number): void;
}

export interface AccessibilityProvider {
  announce(text: string): void;
  setScreenReaderFocus(nodeId: string): void;
  setAltText(nodeId: string, text: string): void;
  setHighContrast(enabled: boolean): void;
}

export interface VRProvider {
  getLeftHand(): VRHand | null;
  getRightHand(): VRHand | null;
  getHeadsetPosition(): Vector3;
  getHeadsetRotation(): Vector3;
  getPointerRay(hand: 'left' | 'right'): { origin: Vector3; direction: Vector3 } | null;
  getDominantHand(): VRHand | null;
}

export interface NetworkProvider {
  broadcastState(nodeId: string, state: Record<string, unknown>): void;
  requestAuthority(nodeId: string): boolean;
  onRemoteUpdate(nodeId: string, callback: (state: Record<string, unknown>) => void): void;
}

export interface RendererProvider {
  createGaussianSplat(nodeId: string, config: Record<string, unknown>): void;
  createPointCloud(nodeId: string, config: Record<string, unknown>): void;
  dispatchCompute(nodeId: string, shader: string, workgroups: number[]): void;
  destroyRenderable(nodeId: string): void;
}

export interface TraitContextFactoryConfig {
  physics?: PhysicsProvider;
  audio?: AudioProvider;
  haptics?: HapticsProvider;
  accessibility?: AccessibilityProvider;
  vr?: VRProvider;
  network?: NetworkProvider;
  renderer?: RendererProvider;
}

export class TraitContextFactory {
  constructor(config?: TraitContextFactoryConfig);
  createContext(): TraitContext;
  setPhysicsProvider(provider: PhysicsProvider): void;
  setAudioProvider(provider: AudioProvider): void;
  setHapticsProvider(provider: HapticsProvider): void;
  setAccessibilityProvider(provider: AccessibilityProvider): void;
  setVRProvider(provider: VRProvider): void;
  setNetworkProvider(provider: NetworkProvider): void;
  setRendererProvider(provider: RendererProvider): void;
  getNetworkProvider(): NetworkProvider | undefined;
  getRendererProvider(): RendererProvider | undefined;
  on(event: string, handler: (payload: unknown) => void): void;
  off(event: string, handler: (payload: unknown) => void): void;
  dispose(): void;
}

export function createTraitContextFactory(config?: TraitContextFactoryConfig): TraitContextFactory;

// ============================================================================
// TRAIT RUNTIME INTEGRATION (migrated from Hololand)
// ============================================================================

export interface TrackedNode {
  node: HSPlusNode;
  traitNames: VRTraitName[];
}

export interface TraitRuntimeStats {
  trackedNodes: number;
  totalTraits: number;
  updatesPerSecond: number;
  lastUpdateMs: number;
}

export class TraitRuntimeIntegration {
  constructor(contextFactory: TraitContextFactory);
  registerNode(node: HSPlusNode): void;
  attachTraitsFromAST(nodes: HSPlusNode[]): void;
  attachTrait(nodeId: string, traitName: VRTraitName, config?: unknown): void;
  detachTrait(nodeId: string, traitName: VRTraitName): void;
  unregisterNode(nodeId: string): void;
  update(delta: number): void;
  dispatchEvent(nodeId: string, event: TraitEvent): void;
  broadcastEvent(event: TraitEvent): void;
  pause(): void;
  resume(): void;
  isPaused(): boolean;
  refreshContext(): void;
  getNode(nodeId: string): HSPlusNode | undefined;
  getNodeTraits(nodeId: string): VRTraitName[];
  getAllNodeIds(): string[];
  getStats(): TraitRuntimeStats;
  getRegistry(): VRTraitRegistry;
  getContext(): TraitContext;
  reset(): void;
  dispose(): void;
}

export function createTraitRuntime(contextFactory: TraitContextFactory): TraitRuntimeIntegration;

// ============================================================================
// HSPLUS VALIDATOR (migrated from Hololand)
// ============================================================================

export interface ParserValidationError {
  type: 'syntax' | 'semantic' | 'runtime' | 'device';
  message: string;
  line?: number;
  column?: number;
  suggestion?: string;
  recoverable: boolean;
}

export interface DeviceOptimizationContext {
  deviceId: string;
  gpuCapability: 'low' | 'medium' | 'high' | 'extreme';
  cpuCapability: 'low' | 'medium' | 'high' | 'extreme';
  targetFPS: number;
  maxGPUMemory: number;
  supportedShaderLevel: 'es2' | 'es3' | 'es31' | 'core';
}

export interface CodeGenerationOptions {
  includeMetadata?: boolean;
  optimizeForDevice?: DeviceOptimizationContext;
  generateImports?: boolean;
  strictMode?: boolean;
  validateDependencies?: boolean;
}

export interface ParserRegistrationResult {
  success: boolean;
  traitId?: string;
  error?: string;
  warnings?: string[];
  metadata?: {
    deviceOptimizations?: string[];
    estimatedMemory?: number;
    performanceImpact?: 'low' | 'medium' | 'high';
  };
}

export interface HSPlusValidationResult {
  valid: boolean;
  errors: ParserValidationError[];
  warnings: ParserValidationError[];
}

export function validateHSPlus(code: string): HSPlusValidationResult;

// ============================================================================
// HS KNOWLEDGE PARSER (migrated from Hololand)
// ============================================================================

export interface HSMeta {
  name: string;
  version: string;
  domain?: string;
  [key: string]: string | undefined;
}

export interface HSKnowledgeChunk {
  id: string;
  category: string;
  content: string;
  tags?: string[];
  [key: string]: any;
}

export interface HSPrompt {
  id: string;
  template: string;
  variables?: string[];
  [key: string]: any;
}

export interface HSRoute {
  method: string;
  path: string;
  handler: string;
  [key: string]: any;
}

export interface HSProvider {
  name: string;
  type: string;
  config?: Record<string, any>;
  [key: string]: any;
}

export interface HSParsedFile {
  meta: HSMeta;
  raw: string;
}

export interface HSKnowledgeFile extends HSParsedFile {
  chunks: HSKnowledgeChunk[];
}

export interface HSPromptFile extends HSParsedFile {
  prompts: HSPrompt[];
}

export interface HSServerFile extends HSParsedFile {
  routes: HSRoute[];
  providers: HSProvider[];
}

export function parseMeta(content: string): HSMeta;
export function parseKnowledge(raw: string): HSKnowledgeFile;
export function parsePrompts(raw: string): HSPromptFile;
export function parseServerRoutes(raw: string): HSServerFile;

// ============================================================================
// HOLOSCRIPT I/O (migrated from Hololand)
// ============================================================================

export interface CoreParseResult {
  success: boolean;
  program?: CoreProgram;
  errors: any[];
}

export interface CoreProgram {
  declarations: CoreDeclaration[];
  statements: CoreStatement[];
}

export interface CoreDeclaration { [key: string]: any; }
export interface CoreStatement { [key: string]: any; }

export interface CoreWorldDeclaration {
  type: 'WorldDeclaration';
  name: string;
  [key: string]: any;
}

export interface CoreOrbDeclaration {
  type: 'OrbDeclaration';
  name: string;
  properties: CoreOrbProperty[];
  [key: string]: any;
}

export interface CoreOrbProperty {
  key: string;
  value: CoreExpression;
}

export interface CoreExpression { [key: string]: any; }

export interface HoloScriptAST { nodes: HoloScriptASTNode[]; }
export interface HoloScriptASTNode { [key: string]: any; }
export interface HoloScriptASTLogic { [key: string]: any; }
export interface HoloScriptExportOptions { [key: string]: any; }
export interface HoloScriptImportOptions { [key: string]: any; }
export interface HoloScriptParseResult { success: boolean; [key: string]: any; }
export interface HoloScriptError { message: string; line?: number; [key: string]: any; }

export function initHoloScriptParser(): void;
export function parseWithCoreParser(source: string): CoreParseResult;
export function expressionToValue(expr: CoreExpression): any;
export function programToInternalAST(program: CoreProgram): HoloScriptAST;
export function extractWorldSettings(program: CoreProgram): Record<string, any>;
export function orbToASTNode(orb: CoreOrbDeclaration): HoloScriptASTNode;
export function parseHoloScriptSimplified(source: string): HoloScriptAST;
export function parseProperties(source: string): Record<string, any>;
export function parseValue(value: string): any;
export function escapeHoloString(str: string): string;
export function formatHoloValue(value: any): string;

// ============================================================================
// SMART ASSET SYSTEM
// ============================================================================

export interface AssetMetadata {
  id: string;
  name: string;
  type: string;
  format: string;
  size: number;
  hash?: string;
  tags?: string[];
  created?: string;
  modified?: string;
  [key: string]: any;
}

export interface AssetManifest {
  version: string;
  assets: AssetMetadata[];
  totalSize: number;
  [key: string]: any;
}

export interface SmartAssetLoader {
  load(id: string, options?: any): Promise<any>;
  preload(ids: string[]): Promise<void>;
  resolve(alias: string): string;
  getManifest(): AssetManifest;
  [key: string]: any;
}

export function getSmartAssetLoader(): SmartAssetLoader;
export function getAssetRegistry(): AssetRegistry;
export function createSmartAssetLoader(config?: any): SmartAssetLoader;
export function resolveAssetAlias(alias: string): string;
export declare const DEFAULT_ASSET_ALIASES: Record<string, string>;

// ============================================================================
// OPTIMIZATION
// ============================================================================

export interface OptimizationReport {
  passes: string[];
  savings: number;
  duration: number;
  before: { size: number; nodes: number };
  after: { size: number; nodes: number };
  [key: string]: any;
}

export interface OptimizationOptions {
  level?: 'none' | 'basic' | 'aggressive';
  passes?: string[];
  target?: string;
  [key: string]: any;
}

// ============================================================================
// GAUSSIAN CODEC
// ============================================================================

export interface GaussianSplatData {
  positions: Float32Array;
  colors: Float32Array;
  opacities: Float32Array;
  scales: Float32Array;
  rotations: Float32Array;
  count: number;
  [key: string]: any;
}

export interface CodecRegistry {
  register(name: string, codec: any): void;
  get(name: string): any;
  list(): string[];
  [key: string]: any;
}

export function getGlobalCodecRegistry(): CodecRegistry;

// ============================================================================
// AVATAR / NPC TRAIT SYSTEM
// ============================================================================

export interface LipSyncConfig {
  model?: string;
  sampleRate?: number;
  visemeMap?: Record<string, string>;
  smoothing?: number;
  [key: string]: any;
}

export type LipSyncEventType = 'viseme' | 'phoneme' | 'silence' | 'start' | 'end';

export interface LipSyncEvent {
  type: LipSyncEventType;
  viseme?: string;
  timestamp: number;
  duration?: number;
  weight?: number;
}

export interface VisemeTimestamp {
  viseme: string;
  start: number;
  end: number;
  weight: number;
}

export declare class LipSyncTrait {
  constructor(config?: LipSyncConfig);
  processAudio(audioData: any): LipSyncEvent[];
  getCurrentViseme(): string | null;
  getVisemeTimestamps(): VisemeTimestamp[];
  update(delta: number): void;
  reset(): void;
  [key: string]: any;
}

export interface EmotionDirectiveConfig {
  emotions?: string[];
  blendDuration?: number;
  intensityScale?: number;
  [key: string]: any;
}

export type EmotionDirectiveEventType = 'emotion_start' | 'emotion_end' | 'emotion_blend' | 'emotion_peak';

export interface EmotionDirectiveEvent {
  type: EmotionDirectiveEventType;
  emotion: string;
  intensity: number;
  timestamp: number;
  [key: string]: any;
}

export interface EmotionTaggedSegment {
  text: string;
  emotion: string;
  intensity: number;
  start: number;
  end: number;
}

export interface EmotionTaggedResponse {
  segments: EmotionTaggedSegment[];
  dominantEmotion: string;
  overallIntensity: number;
  [key: string]: any;
}

export interface TriggeringDirective {
  condition: string;
  emotion: string;
  intensity: number;
  [key: string]: any;
}

export interface ConditionalDirective {
  if: string;
  then: string;
  else?: string;
  [key: string]: any;
}

export declare class EmotionDirectiveTrait {
  constructor(config?: EmotionDirectiveConfig);
  processText(text: string): EmotionTaggedResponse;
  setEmotion(emotion: string, intensity?: number): void;
  getCurrentEmotion(): { emotion: string; intensity: number } | null;
  blendTo(emotion: string, intensity: number, duration?: number): void;
  update(delta: number): void;
  reset(): void;
  [key: string]: any;
}

export interface AvatarEmbodimentConfig {
  skeleton?: string;
  blendShapes?: string[];
  pipeline?: PipelineStage[];
  [key: string]: any;
}

export interface PipelineStage {
  name: string;
  type: string;
  config?: Record<string, any>;
  order?: number;
  enabled?: boolean;
  [key: string]: any;
}

export interface AIDriverConfig {
  model?: string;
  behaviorTree?: string;
  perception?: { range: number; fov: number; [key: string]: any };
  navigation?: { speed: number; avoidance: boolean; [key: string]: any };
  [key: string]: any;
}

export interface NPCContext {
  id: string;
  position: SpatialPosition;
  state: Record<string, any>;
  memory?: any[];
  currentGoal?: string;
  [key: string]: any;
}

export declare class AIDriverTrait {
  constructor(config?: AIDriverConfig);
  initialize(context: NPCContext): void;
  update(delta: number, context: NPCContext): void;
  setGoal(goal: string): void;
  getState(): Record<string, any>;
  perceive(entities: any[]): any[];
  decide(context: NPCContext): string;
  [key: string]: any;
}

// ============================================================================
// CROSS-PLATFORM COMPILERS (re-exported from compiler subpaths)
// ============================================================================

export class UnityCompiler { constructor(options?: any); compile(ast: any, options?: any): any; [key: string]: any; }
export class GodotCompiler { constructor(options?: any); compile(ast: any, options?: any): any; [key: string]: any; }
export class VisionOSCompiler { constructor(options?: any); compile(ast: any, options?: any): any; [key: string]: any; }
export class VRChatCompiler { constructor(options?: any); compile(ast: any, options?: any): any; [key: string]: any; }
export class UnrealCompiler { constructor(options?: any); compile(ast: any, options?: any): any; [key: string]: any; }

// ============================================================================
// REACTIVE STATE SYSTEM
// ============================================================================

export function reactive<T extends object>(target: T): T;
export function effect(fn: () => void): () => void;
export function computed<T>(getter: () => T): { readonly value: T };
export function bind(target: any, key: string, source: any, sourceKey?: string): void;
export function createState(initial?: Record<string, any>): ReactiveState;

// ============================================================================
// PARSER FACTORIES & VARIANTS
// ============================================================================

export class HoloScriptParser { parse(source: string): ParseResult; [key: string]: any; }
export class HoloScript2DParser { parse(source: string): ParseResult; [key: string]: any; }
export function createParser(options?: HSPlusParserOptions): HoloScriptPlusParser;
export function createDebugger(options?: any): HoloScriptDebugger;
export function createHoloScriptEnvironment(options?: any): any;

// ============================================================================
// RUNTIME CONTEXT & ENVIRONMENT
// ============================================================================

export interface RuntimeContext {
  runtime: HoloScriptRuntime;
  renderer?: Renderer;
  state?: Record<string, any>;
  [key: string]: any;
}

export interface HoloImport {
  source: string;
  specifiers: string[];
  [key: string]: any;
}

export interface HoloParseError {
  message: string;
  line?: number;
  column?: number;
  source?: string;
  [key: string]: any;
}

export interface HologramProperties {
  position?: SpatialPosition;
  scale?: { x: number; y: number; z: number };
  rotation?: { x: number; y: number; z: number };
  visible?: boolean;
  [key: string]: any;
}

export interface DebugEvent {
  type: string;
  data?: any;
  timestamp?: number;
  [key: string]: any;
}

export interface DebugState {
  paused: boolean;
  currentLine?: number;
  breakpoints: number[];
  callStack: any[];
  [key: string]: any;
}

export type StepMode = 'into' | 'over' | 'out';

// ============================================================================
// AST NODE VARIANTS
// ============================================================================

export interface ConnectionNode extends ASTNode { type: 'Connection'; from: string; to: string; [key: string]: any; }
export interface GateNode extends ASTNode { type: 'Gate'; condition: string; [key: string]: any; }
export interface StreamNode extends ASTNode { type: 'Stream'; name: string; [key: string]: any; }
export interface TransformationNode extends ASTNode { type: 'Transformation'; [key: string]: any; }
export interface MethodNode extends ASTNode { type: 'Method'; name: string; parameters: ParameterNode[]; [key: string]: any; }
export interface ParameterNode extends ASTNode { type: 'Parameter'; name: string; paramType?: string; [key: string]: any; }

// ============================================================================
// 2D UI TYPES
// ============================================================================

export interface Position2D { x: number; y: number; }
export interface Size2D { width: number; height: number; }
export type UIElementType = 'button' | 'text' | 'panel' | 'image' | 'input' | 'slider' | 'toggle' | string;
export interface UIStyle { [key: string]: any; }
export interface UI2DNode extends ASTNode { type: 'UI2D'; elementType: UIElementType; style?: UIStyle; children?: UI2DNode[]; [key: string]: any; }

// ============================================================================
// VOICE & GESTURE
// ============================================================================

export interface VoiceCommand { phrase: string; action: string; confidence?: number; [key: string]: any; }
export interface GestureData { type: string; confidence: number; hand?: 'left' | 'right'; [key: string]: any; }

// ============================================================================
// CONSTANTS & LOGGING
// ============================================================================

export declare const HOLOSCRIPT_VERSION: string;
export declare const HOLOSCRIPT_DEMO_SCRIPTS: Record<string, string>;
export declare const HOLOSCRIPT_GESTURES: string[];
export declare const HOLOSCRIPT_SUPPORTED_PLATFORMS: string[];
export declare const HOLOSCRIPT_VOICE_COMMANDS: VoiceCommand[];

export interface Logger { info(...args: any[]): void; warn(...args: any[]): void; error(...args: any[]): void; debug(...args: any[]): void; }
export class ConsoleLogger implements Logger { info(...args: any[]): void; warn(...args: any[]): void; error(...args: any[]): void; debug(...args: any[]): void; }
export class NoOpLogger implements Logger { info(...args: any[]): void; warn(...args: any[]): void; error(...args: any[]): void; debug(...args: any[]): void; }
export type HoloScriptLogger = Logger;
export function setHoloScriptLogger(logger: Logger): void;
export function resetLogger(): void;
export function enableConsoleLogging(): void;
export const logger: HoloScriptLogger;
export function isHoloScriptSupported(): boolean;

// ============================================================================
// CULTURE TYPES
// ============================================================================

export interface CulturalNorm {
  [key: string]: any;
}
export type NormCategory = string;
export type NormEnforcement = 'hard' | 'soft' | 'advisory';
export type NormScope = 'agent' | 'zone' | 'world' | 'session';
export type NormProvenanceSource =
  | 'agent'
  | 'corpus'
  | 'declaration_site'
  | 'builtin'
  | 'observation'
  | 'unknown';
export interface NormProvenance {
  source: NormProvenanceSource;
  sourceAgentId?: string;
  sourceCorpus?: string;
  declarationSite?: {
    file: string;
    line?: number;
    column?: number;
  };
  originInteractionId?: string;
  confidenceClassification?: 'genuine' | 'confabulated' | 'bullshitted';
  recordedAtIso?: string;
}
export declare const UNKNOWN_NORM_PROVENANCE: Readonly<NormProvenance>;
export declare const BUILTIN_NORM_PROVENANCE: Readonly<NormProvenance>;
export declare function normalizeNormProvenance(
  value: Partial<NormProvenance> | undefined | null
): NormProvenance;
export declare function serializeNormProvenance(
  value: NormProvenance | undefined | null
): Record<string, unknown>;
export declare function deserializeNormProvenance(value: unknown): NormProvenance;

// ============================================================================
// MARKETPLACE
// ============================================================================

export type ContentCategory = string;

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

// ============================================================================
// DEFAULT EXPORT
// ============================================================================

declare const _default: {
  parse: typeof parse;
  parseHolo: typeof parseHolo;
  parseHoloStrict: typeof parseHoloStrict;
  parseHoloScriptPlus: typeof parseHoloScriptPlus;
  HoloScriptPlusParser: typeof HoloScriptPlusParser;
  HoloCompositionParser: typeof HoloCompositionParser;
  HoloScriptCodeParser: typeof HoloScriptCodeParser;
  HoloScriptCompiler: typeof HoloScriptCompiler;
  HoloScriptRuntime: typeof HoloScriptRuntime;
  HoloScriptPlusRuntimeImpl: typeof HoloScriptPlusRuntimeImpl;
  HoloScriptTypeChecker: typeof HoloScriptTypeChecker;
  HoloScriptDebugger: typeof HoloScriptDebugger;
  TraitCompositor: typeof TraitCompositor;
  createRuntime: typeof createRuntime;
  MATERIAL_PRESETS: typeof MATERIAL_PRESETS;
};
export default _default;

// ============================================================================
// ANIMATION ENGINE
// ============================================================================

export type EasingFn = (t: number) => number;
export declare const Easing: {
  readonly linear: (t: number) => number;
  readonly easeInQuad: (t: number) => number;
  readonly easeOutQuad: (t: number) => number;
  readonly easeInOutQuad: (t: number) => number;
  readonly easeInCubic: (t: number) => number;
  readonly easeOutCubic: (t: number) => number;
  readonly easeInOutCubic: (t: number) => number;
  readonly easeInExpo: (t: number) => number;
  readonly easeOutExpo: (t: number) => number;
  readonly easeInOutExpo: (t: number) => number;
  readonly easeOutBack: (t: number) => number;
  readonly easeOutElastic: (t: number) => number;
  readonly easeOutBounce: (t: number) => number;
};
export interface Keyframe<T = number> { time: number; value: T; easing?: EasingFn; }
export interface AnimationClip { id: string; property: string; keyframes: Keyframe[]; duration: number; loop: boolean; pingPong: boolean; delay: number; onComplete?: () => void; }
export interface ActiveAnimation { clip: AnimationClip; elapsed: number; isPlaying: boolean; isPaused: boolean; direction: 1 | -1; loopCount: number; }
export declare class AnimationEngine {
  play(clip: AnimationClip, setter: (value: any) => void): void;
  stop(clipId: string): void;
  pause(clipId: string): void;
  resume(clipId: string): void;
  isActive(clipId: string): boolean;
  getActiveIds(): string[];
  update(delta: number): void;
  clear(): void;
}
export interface SampledKeyframe { time: number; value: number; easing?: string; }
export declare function applyEasing(t: number, easing: string): number;
export declare function sampleTrack(
  keyframes: SampledKeyframe[],
  t: number,
  defaultEasing?: string
): number;

// ============================================================================
// AUDIO ENGINE
// ============================================================================

export type DistanceModel = 'linear' | 'inverse' | 'exponential';
export interface AudioSourceConfig { id: string; position: { x: number; y: number; z: number }; volume: number; pitch: number; loop: boolean; maxDistance: number; refDistance: number; rolloffFactor: number; distanceModel: DistanceModel; channel: string; spatialize: boolean; }
export interface AudioSource { config: AudioSourceConfig; isPlaying: boolean; currentTime: number; computedVolume: number; computedPan: number; soundId: string; }
export declare class AudioEngine {
  setListenerPosition(pos: { x: number; y: number; z: number }): void;
  setListenerOrientation(forward: { x: number; y: number; z: number }, up: { x: number; y: number; z: number }): void;
  getListener(): any;
  play(soundId: string, config?: Partial<AudioSourceConfig>): string;
  stop(sourceId: string): void;
  setSourcePosition(sourceId: string, pos: { x: number; y: number; z: number }): void;
  update(delta: number): void;
  getSource(sourceId: string): AudioSource | undefined;
  getActiveSources(): AudioSource[];
  setMasterVolume(vol: number): void;
  getMasterVolume(): number;
  setMuted(muted: boolean): void;
  isMuted(): boolean;
  getActiveCount(): number;
  stopAll(): void;
}

// ============================================================================
// PARTICLE SYSTEM
// ============================================================================

export interface EmitterConfig { [key: string]: any; }
export interface Particle { [key: string]: any; }
export interface Color4 { r: number; g: number; b: number; a: number; }
export declare class ParticleSystem {
  constructor(config: EmitterConfig);
  update(delta: number): void;
  emit(count?: number): void;
  clear(): void;
  getParticles(): Particle[];
  getActiveCount(): number;
  setConfig(config: Partial<EmitterConfig>): void;
  getConfig(): EmitterConfig;
  [key: string]: any;
}

// ============================================================================
// SHADER GRAPH
// ============================================================================

export declare class ShaderGraph {
  readonly id: string;
  nodes: Map<string, any>;
  connections: any[];
  constructor(id?: string);
  addNode(node: any): void;
  removeNode(nodeId: string): void;
  connect(fromId: string, fromPort: string, toId: string, toPort: string): void;
  disconnect(connectionId: string): void;
  compile(target?: string): string;
  toJSON(): any;
  static fromJSON(data: any): ShaderGraph;
  [key: string]: any;
}

// ============================================================================
// RUNTIME ENGINES
// ============================================================================

export declare class CameraController { constructor(config?: any); setMode(mode: string): void; getMode(): string; update(delta: number, input?: any): void; setTarget(target: any): void; getTransform(): any; [key: string]: any; }
export declare class AStarPathfinder { constructor(grid?: any); findPath(start: any, end: any): any[]; setGrid(grid: any): void; [key: string]: any; }
export type LightType = 'directional' | 'point' | 'spot' | 'area' | 'probe';
export declare class LightingModel { addLight(type: 'directional' | 'point' | 'spot', config?: any): string; removeLight(id: string): void; updateLight(id: string, config: any): void; getLights(): any[]; update(delta: number): void; [key: string]: any; }
export declare class CinematicDirector { play(sequence: any): void; stop(): void; pause(): void; resume(): void; update(delta: number): void; [key: string]: any; }
export declare class SaveManager { constructor(config?: any); save(key: string, data: any): Promise<void>; load(key: string): Promise<any>; delete(key: string): Promise<void>; list(): Promise<string[]>; [key: string]: any; }
export declare class Profiler { begin(label: string): void; end(label: string): number; getStats(): Record<string, any>; reset(): void; [key: string]: any; }

// ============================================================================
// SANDBOX
// ============================================================================

export interface Sandbox { [key: string]: any; }
export interface SandboxExecutionResult { success: boolean; result?: any; error?: string; memoryUsed: number; cpuTimeUsed: number; }
export declare function createSandbox(policy: any): Sandbox;
export declare function executeSandbox(code: string, sandbox: Sandbox): Promise<SandboxExecutionResult>;
export declare function destroySandbox(sandbox: Sandbox): void;
export declare class SandboxExecutor { constructor(config?: any); execute(code: string): Promise<SandboxExecutionResult>; [key: string]: any; }
export declare function quickSafetyCheck(traits: string[], builtins: string[], options?: { trustLevel?: string; targetPlatform?: string }): { passed: boolean; verdict: string; reasons: string[] };
export declare function buildSafetyReport(result: any): SafetyReport;
export declare function formatReport(report: SafetyReport): string;
export declare function generateCertificate(report: SafetyReport): string;

// ============================================================================
// LOD / TILEMAP
// ============================================================================

export interface LODLevel { level: number; distance: number; polygonRatio: number; textureScale: number; disabledFeatures: string[]; [key: string]: any; }
export interface LODConfig { id: string; levels: LODLevel[]; [key: string]: any; }
export declare class LODManager { register(id: string, config: LODConfig): void; unregister(id: string): void; update(cameraPosition: any): void; getActiveLevel(id: string): LODLevel | null; [key: string]: any; }
export interface TileData { id: number; flags: number; [key: string]: any; }
export declare const TileFlags: { readonly NONE: 0; readonly SOLID: 1; readonly WALKABLE: 2; readonly WATER: 4; [key: string]: number; };
export declare class TileMap { constructor(width: number, height: number, tileSize?: number); addLayer(name: string): void; removeLayer(name: string): void; setTile(layer: string, x: number, y: number, tile: TileData): void; getTile(layer: string, x: number, y: number): TileData | undefined; removeTile(layer: string, x: number, y: number): void; getTileSize(): number; getLayerCount(): number; [key: string]: any; }

// ============================================================================
// STATE / NETWORK
// ============================================================================

export interface StateDeclaration { name: string; type: string; [key: string]: any; }
export declare class ReactiveState<T extends StateDeclaration = StateDeclaration> { constructor(initial: Record<string, any>); set(key: keyof T, value: any): void; get(key: keyof T): any; getSnapshot(): Record<string, any>; undo(): void; redo(): void; subscribe(listener: (state: Record<string, any>) => void): () => void; [key: string]: any; }
export type MessageType = 'state_sync' | 'event' | 'rpc' | 'handshake' | 'heartbeat' | 'agent_state';
export declare class NetworkManager { constructor(config?: any); connect(url: string): Promise<void>; disconnect(): void; send(type: MessageType, payload: any): void; on(type: MessageType, handler: (payload: any) => void): void; off(type: MessageType, handler: (payload: any) => void): void; isConnected(): boolean; [key: string]: any; }
export declare class MultiplayerSession { constructor(config?: any); join(roomId: string): Promise<void>; leave(): Promise<void>; broadcast(event: string, data: any): void; on(event: string, handler: (data: any) => void): void; getConnectedPeers(): string[]; [key: string]: any; }

// ============================================================================
// ASSET REGISTRY
// ============================================================================

export interface AssetEntry { id: string; type: string; url: string; name: string; [key: string]: any; }
export declare class AssetRegistry {
  constructor(config?: any);
  register(entry: AssetEntry): void;
  unregister(id: string): void;
  get(id: string): AssetEntry | undefined;
  getByType(type: string): AssetEntry[];
  getAll(): AssetEntry[];
  load(id: string): Promise<any>;
  preload(ids: string[]): Promise<void>;
  [key: string]: any;
}

// ============================================================================
// TERRAIN SYSTEM
// ============================================================================

export interface TerrainLayer { [key: string]: any; }
export interface TerrainConfig { width: number; depth: number; heightScale?: number; layers?: TerrainLayer[]; [key: string]: any; }
export declare class TerrainSystem {
  constructor(config?: TerrainConfig);
  generate(config?: Partial<TerrainConfig>): void;
  getHeight(x: number, z: number): number;
  getNormal(x: number, z: number): any;
  update(delta: number): void;
  getConfig(): TerrainConfig;
  [key: string]: any;
}

// ============================================================================
// STATE MACHINE
// ============================================================================

export interface StateMachineState { name: string; onEnter?: () => void; onExit?: () => void; onUpdate?: (delta: number) => void; [key: string]: any; }
export interface StateMachineTransition { from: string; to: string; condition: () => boolean; [key: string]: any; }
export declare class StateMachine {
  constructor(states?: StateMachineState[], transitions?: StateMachineTransition[]);
  addState(state: StateMachineState): void;
  addTransition(transition: StateMachineTransition): void;
  start(initialState: string): void;
  stop(): void;
  update(delta: number): void;
  getCurrentState(): string | null;
  transition(to: string): void;
  [key: string]: any;
}

// ============================================================================
// TIMELINE
// ============================================================================

export type TimelineMode = 'once' | 'loop' | 'pingpong';
export interface TimelineEntry { time: number; action: () => void; }
export interface TimelineConfig { duration: number; mode?: TimelineMode; entries?: TimelineEntry[]; }
export declare class Timeline {
  constructor(config?: TimelineConfig);
  addEntry(entry: TimelineEntry): void;
  play(): void;
  pause(): void;
  stop(): void;
  update(delta: number): void;
  seek(time: number): void;
  getDuration(): number;
  getCurrentTime(): number;
  [key: string]: any;
}

// ============================================================================
// SCENE MANAGER
// ============================================================================

export interface SceneListEntry { id: string; name: string; description?: string; thumbnail?: string; [key: string]: any; }
export declare class SceneManager {
  constructor(config?: any);
  getScenes(): SceneListEntry[];
  getScene(id: string): SceneListEntry | undefined;
  addScene(scene: SceneListEntry): void;
  removeScene(id: string): void;
  loadScene(id: string): Promise<any>;
  saveScene(id: string, data: any): Promise<void>;
  [key: string]: any;
}

// ============================================================================
// SAVE SLOT (used by useSaveLoad)
// ============================================================================

export interface SaveSlot { id: string; name: string; data: any; timestamp: number; [key: string]: any; }

// ============================================================================
// NAV MESH / PATHFINDING
// ============================================================================

export interface NavPoint { x: number; y: number; z: number; [key: string]: any; }
export interface PathResult { path: NavPoint[]; cost: number; success: boolean; }
export declare class NavMesh {
  constructor(config?: any);
  build(geometry: any): void;
  findPath(start: NavPoint, end: NavPoint): PathResult;
  isWalkable(point: NavPoint): boolean;
  [key: string]: any;
}

// ============================================================================
// ECS WORLD
// ============================================================================

export interface TransformComponent { position: { x: number; y: number; z: number }; rotation: { x: number; y: number; z: number; w: number }; scale: { x: number; y: number; z: number }; }
export declare class ECSWorld {
  constructor();
  createEntity(): number;
  destroyEntity(entity: number): void;
  addComponent<T>(entity: number, componentType: number, data: T): void;
  removeComponent(entity: number, componentType: number): void;
  getComponent<T>(entity: number, componentType: number): T | undefined;
  query(...componentTypes: number[]): number[];
  update(delta: number): void;
  [key: string]: any;
}

// ============================================================================
// INPUT MANAGER
// ============================================================================

export declare class InputManager {
  constructor(config?: any);
  isKeyDown(key: string): boolean;
  isKeyPressed(key: string): boolean;
  isMouseDown(button: number): boolean;
  getMousePosition(): { x: number; y: number };
  getMouseDelta(): { x: number; y: number };
  bindAction(name: string, keys: string[]): void;
  isActionPressed(name: string): boolean;
  update(): void;
  [key: string]: any;
}

// ============================================================================
// CULTURE RUNTIME
// ============================================================================

export interface CultureEvent { type: string; data: any; [key: string]: any; }
export declare class CultureRuntime {
  constructor(config?: any);
  loadNorms(norms: any[]): void;
  evaluate(context: any): { violations: any[]; score: number };
  on(event: string, handler: (e: CultureEvent) => void): void;
  emit(event: CultureEvent): void;
  [key: string]: any;
}

// ============================================================================
// COMBAT MANAGER
// ============================================================================

export interface HitBox { x: number; y: number; z: number; width: number; height: number; depth: number; [key: string]: any; }
export interface HurtBox { x: number; y: number; z: number; width: number; height: number; depth: number; [key: string]: any; }
export interface ComboChain { id: string; attacks: string[]; window: number; [key: string]: any; }
export declare class CombatManager {
  constructor(config?: any);
  registerHitBox(entityId: string, hitBox: HitBox): void;
  registerHurtBox(entityId: string, hurtBox: HurtBox): void;
  registerCombo(chain: ComboChain): void;
  checkCollisions(): Array<{ attacker: string; defender: string; damage: number }>;
  update(delta: number): void;
  [key: string]: any;
}

// ============================================================================
// COLLABORATION SESSION
// ============================================================================

export interface SessionPeer { id: string; name: string; color: string; [key: string]: any; }
export interface SessionStats { peerCount: number; latency: number; uptime: number; [key: string]: any; }
export declare class CollaborationSession {
  constructor(config?: any);
  join(sessionId: string, peer: SessionPeer): Promise<void>;
  leave(): Promise<void>;
  getPeers(): SessionPeer[];
  getStats(): SessionStats;
  broadcast(event: string, data: any): void;
  on(event: string, handler: (data: any) => void): void;
  [key: string]: any;
}

// ============================================================================
// CINEMATIC TYPES
// ============================================================================

export interface CinematicScene { id: string; duration: number; cues: CuePoint[]; [key: string]: any; }
export interface CuePoint { time: number; action: string; params?: any; [key: string]: any; }

// ============================================================================
// BEHAVIOR TREE
// ============================================================================

export type BehaviorStatus = 'success' | 'failure' | 'running';
export interface BehaviorNode { tick(agent: any): BehaviorStatus; [key: string]: any; }
export declare class BehaviorTree {
  constructor(root: BehaviorNode);
  tick(agent: any): BehaviorStatus;
  setRoot(node: BehaviorNode): void;
  [key: string]: any;
}

// ============================================================================
// DIALOGUE SYSTEM
// ============================================================================

export interface DialogueNode { id: string; text: string; speaker?: string; choices?: DialogueChoice[]; [key: string]: any; }
export interface DialogueChoice { id: string; text: string; nextId: string; condition?: string; [key: string]: any; }
export interface DialogueTree { id: string; nodes: DialogueNode[]; startId: string; [key: string]: any; }
export declare class DialogueManager {
  constructor(config?: any);
  loadTree(tree: DialogueTree): void;
  startDialogue(treeId: string): DialogueNode | null;
  selectChoice(choiceId: string): DialogueNode | null;
  getCurrentNode(): DialogueNode | null;
  isActive(): boolean;
  [key: string]: any;
}

// ============================================================================
// INVENTORY SYSTEM
// ============================================================================

export interface InventoryItem { id: string; name: string; type: string; quantity: number; [key: string]: any; }
export interface Inventory { id: string; slots: number; items: InventoryItem[]; [key: string]: any; }
export declare class InventoryManager {
  constructor(config?: any);
  createInventory(id: string, slots: number): Inventory;
  addItem(inventoryId: string, item: InventoryItem): boolean;
  removeItem(inventoryId: string, itemId: string, quantity?: number): boolean;
  getItems(inventoryId: string): InventoryItem[];
  [key: string]: any;
}

// ============================================================================
// LIGHTING TYPES
// ============================================================================

export interface Light { id: string; type: LightType; color: string; intensity: number; [key: string]: any; }
export interface AmbientConfig { color: string; intensity: number; [key: string]: any; }

// ============================================================================
// COMPILER TYPES  
// ============================================================================

export interface CompilerTarget { [key: string]: any; }
export interface TraitDefinition { name: string; properties?: Record<string, any>; [key: string]: any; }
export interface CompilerPlugin { [key: string]: any; }
export interface CompilerOptions { target?: string; optimize?: boolean; [key: string]: any; }
export interface CompilerDiagnostic { severity: 'error' | 'warning' | 'info'; message: string; line?: number; column?: number; [key: string]: any; }
export interface IncrementalBuildResult { success: boolean; diagnostics: CompilerDiagnostic[]; artifacts: any[]; [key: string]: any; }
export declare class IncrementalCompiler {
  static deserialize(json: string): IncrementalCompiler;
  constructor(config?: any);
  addSource(id: string, source: string): void;
  compile(ast: HoloComposition, compileObject: (obj: any) => string, options?: any): Promise<any>;
  invalidate(id: string): void;
  [key: string]: any;
}
export declare function createIncrementalCompiler(config?: any): IncrementalCompiler;

// ============================================================================
// ECS INSPECTOR TYPES
// ============================================================================

export interface ComponentInfo { type: number; data: any; name: string; }
export interface EntityStats { id: number; components: ComponentInfo[]; active: boolean; }
export declare class ECSInspector {
  constructor(world: ECSWorld);
  getEntityStats(entityId: number): EntityStats;
  getAllEntities(): EntityStats[];
  [key: string]: any;
}

// ============================================================================
// PHYSICS PREVIEW TYPES
// ============================================================================

export interface PhysicsBody { id: string; position: { x: number; y: number; z: number }; velocity: { x: number; y: number; z: number }; mass: number; [key: string]: any; }
export declare class PhysicsWorld {
  constructor(config?: any);
  addBody(body: PhysicsBody): void;
  removeBody(id: string): void;
  step(delta: number): void;
  raycast(from: any, to: any): any;
  [key: string]: any;
}

// ============================================================================
// MARKETPLACE TYPES
// ============================================================================

export type MarketplaceSubmissionStatus = 'draft' | 'pending' | 'verified' | 'published' | 'rejected';
export interface MarketplaceSubmission { id: string; title: string; description: string; category: string; price: number; status: MarketplaceSubmissionStatus; [key: string]: any; }

// ============================================================================
// PLATFORM TARGET TYPES
// ============================================================================

export type PlatformTarget = 'quest3' | 'pcvr' | 'visionos' | 'android-xr' | 'visionos-ar' | 'android-xr-ar' | 'webxr' | 'ios' | 'android' | 'windows' | 'macos' | 'linux' | 'web' | 'android-auto' | 'carplay' | 'watchos' | 'wearos';

// ============================================================================
// DRAFT TRAIT (Draft→Mesh→Simulation Pipeline)
// ============================================================================

export type DraftShape = 'box' | 'sphere' | 'cylinder' | 'cone' | 'capsule' | 'plane' | 'torus';

export interface DraftConfig {
  shape: DraftShape;
  collision: boolean;
  color: string;
  opacity: number;
  wireframe: boolean;
  collisionScale: number;
  targetMaturity: AssetMaturity;
}

export declare const DRAFT_DEFAULTS: DraftConfig;

export declare const DRAFT_TRAIT: {
  readonly name: '@draft';
  readonly version: '1.0.0';
  readonly description: string;
  readonly category: 'pipeline';
  readonly properties: Record<string, any>;
};

export declare class DraftManager {
  setDraft(entityId: string, config?: Partial<DraftConfig>): DraftConfig;
  getDraft(entityId: string): DraftConfig | null;
  isDraft(entityId: string): boolean;
  promote(entityId: string): AssetMaturity;
  demote(entityId: string, config?: Partial<DraftConfig>): DraftConfig;
  getDraftIds(): string[];
  readonly count: number;
  clear(): void;
  demoteAll(entityIds: string[], shape?: DraftShape): void;
  getCollisionShape(entityId: string): DraftShape | null;
}

// ============================================================================
// VR PERFORMANCE REGRESSION MONITOR
// ============================================================================

export interface PerformanceRegressionConfig {
  thresholdMs: number;
  consecutiveFrames: number;
  recoveryFrames: number;
  recoveryThresholdMs: number;
  enabled: boolean;
}

export interface PerformanceRegressionState {
  avgFrameTimeMs: number;
  isRegressed: boolean;
  aboveCount: number;
  belowCount: number;
  regressionCount: number;
  recoveryCount: number;
}

export declare const PERF_REGRESSION_DEFAULTS: PerformanceRegressionConfig;

export declare class PerformanceRegressionMonitor {
  constructor(config?: Partial<PerformanceRegressionConfig>);
  tick(deltaMs: number): PerformanceRegressionState;
  getState(): PerformanceRegressionState;
  forceRegress(): void;
  forceRecover(): void;
  reset(): void;
}

// ============================================================================
// PLUGIN SYSTEM (Sandboxing, API, Lifecycle)
// ============================================================================

export interface PluginSandboxOptions {
  maxMemoryMB?: number;
  timeoutMs?: number;
  allowedAPIs?: string[];
  [key: string]: any;
}

export declare class PluginSandbox {
  constructor(options?: PluginSandboxOptions);
  load(manifest: any): Promise<void>;
  unload(): Promise<void>;
  call(method: string, ...args: any[]): Promise<any>;
  getState(): string;
  [key: string]: any;
}

export declare function createPluginSandbox(options?: PluginSandboxOptions): PluginSandbox;

export declare class PluginAPI {
  constructor(config?: any);
  registerCommand(name: string, handler: (...args: any[]) => any): void;
  getAssets(): any[];
  [key: string]: any;
}

export declare class PluginLoader {
  constructor();
  loadFromManifest(manifest: any): Promise<any>;
  validateManifest(manifest: any): boolean;
  [key: string]: any;
}

export declare class ModRegistry {
  constructor();
  register(entry: any): void;
  resolve(name: string): any;
  detectConflicts(): any[];
  [key: string]: any;
}

export declare class HololandExtensionRegistry {
  constructor();
  registerExtension(type: string, extension: any): void;
  getExtensions(type: string): any[];
  [key: string]: any;
}

// ============================================================================
// POST-QUANTUM CRYPTOGRAPHY (Hybrid Classical + PQ)
// ============================================================================

export interface HybridKeyPair {
  classicalPublicKey: Uint8Array;
  classicalPrivateKey: Uint8Array;
  pqPublicKey: Uint8Array;
  pqPrivateKey: Uint8Array;
  [key: string]: any;
}

export interface HybridSignature {
  classicalSignature: Uint8Array;
  pqSignature: Uint8Array;
  algorithm: string;
  [key: string]: any;
}

export interface HybridCryptoConfig {
  classicalAlgorithm?: string;
  pqAlgorithm?: string;
  [key: string]: any;
}

export declare class HybridCryptoProvider {
  constructor(config?: HybridCryptoConfig);
  generateKeyPair(): Promise<HybridKeyPair>;
  sign(data: Uint8Array, privateKey: any): Promise<HybridSignature>;
  verify(data: Uint8Array, signature: HybridSignature, publicKey: any): Promise<boolean>;
  [key: string]: any;
}

export declare function getHybridCryptoProvider(): HybridCryptoProvider;
export declare function resetHybridCryptoProvider(): void;

// ============================================================================
// x402 PAYMENT PROTOCOL (HTTP 402 + USDC Settlement)
// ============================================================================

export declare const X402_VERSION: number;
export declare const MICRO_PAYMENT_THRESHOLD: number;
export declare const USDC_CONTRACTS: Record<SettlementChain, string>;
export declare const CHAIN_IDS: Record<string, number>;
export declare const CHAIN_ID_TO_NETWORK: Record<number, SettlementChain>;

export type SettlementChain = 'base' | 'base-sepolia' | 'solana' | 'solana-devnet';
export type PaymentScheme = 'exact';
export type SettlementMode = 'in_memory' | 'on_chain';
export type SettlementEventType =
  | 'payment:authorization_created'
  | 'payment:verification_started'
  | 'payment:verification_passed'
  | 'payment:verification_failed'
  | 'payment:settlement_started'
  | 'payment:settlement_completed'
  | 'payment:settlement_failed'
  | 'payment:refund_initiated'
  | 'payment:refund_completed'
  | 'payment:refund_failed'
  | 'payment:batch_settlement_started'
  | 'payment:batch_settlement_completed';
export type SettlementEventListener = (event: SettlementEvent) => void;

export interface X402PaymentRequired {
  x402Version: number;
  accepts: X402PaymentOption[];
  error: string;
}

export interface X402PaymentOption {
  scheme: PaymentScheme;
  network: SettlementChain;
  maxAmountRequired: string;
  resource: string;
  description: string;
  payTo: string;
  asset: string;
  maxTimeoutSeconds: number;
}

export interface X402PaymentPayload {
  x402Version: number;
  scheme: PaymentScheme;
  network: SettlementChain;
  payload: {
    signature: string;
    authorization: {
      from: string;
      to: string;
      value: string;
      validAfter: string;
      validBefore: string;
      nonce: string;
    };
  };
}

export interface X402SettlementResult {
  success: boolean;
  transaction: string | null;
  network: SettlementChain | 'in_memory';
  payer: string;
  errorReason: string | null;
  mode: SettlementMode;
  settledAt: number;
}

export interface X402VerificationResult {
  isValid: boolean;
  invalidReason: string | null;
}

export interface X402FacilitatorConfig {
  recipientAddress: string;
  chain: SettlementChain;
  secondaryChain?: SettlementChain;
  microPaymentThreshold?: number;
  maxTimeoutSeconds?: number;
  optimisticExecution?: boolean;
  batchSettlementIntervalMs?: number;
  maxLedgerEntries?: number;
  facilitatorUrl?: string;
  resourceDescription?: string;
}

export interface CreditTraitConfig {
  price: number;
  chain: SettlementChain;
  recipient: string;
  description: string;
  timeout: number;
  secondary_chain?: SettlementChain;
  optimistic: boolean;
  micro_threshold?: number;
}

export interface LedgerEntry {
  id: string;
  from: string;
  to: string;
  amount: number;
  resource: string;
  timestamp: number;
  settled: boolean;
  settlementTx: string | null;
}

export interface SettlementEvent {
  type: SettlementEventType;
  timestamp: string;
  eventId: string;
  nonce: string | null;
  payer: string | null;
  recipient: string | null;
  amount: string | null;
  network: SettlementChain | 'in_memory' | null;
  transaction: string | null;
  metadata: Record<string, unknown>;
}

export interface RefundRequest {
  originalNonce: string;
  reason: string;
  partialAmount: string | null;
}

export interface RefundResult {
  success: boolean;
  refundId: string;
  amountRefunded: string;
  originalNonce: string;
  transaction: string | null;
  originalMode: SettlementMode;
  reason: string;
  errorReason: string | null;
  refundedAt: number;
}

export declare class MicroPaymentLedger {
  constructor(maxEntries?: number);
  record(from: string, to: string, amount: number, resource: string): LedgerEntry;
  getUnsettled(): LedgerEntry[];
  markSettled(entryIds: string[], txHash: string): void;
  getBalance(address: string): number;
  getUnsettledVolume(): number;
  getEntriesForPayer(from: string): LedgerEntry[];
  getStats(): {
    totalEntries: number;
    unsettledEntries: number;
    unsettledVolume: number;
    uniquePayers: number;
    uniqueRecipients: number;
  };
  pruneSettled(): number;
  reset(): void;
}

export declare class X402Facilitator {
  constructor(config: X402FacilitatorConfig);
  createPaymentRequired(resource: string, amountUSDC: number, description?: string): X402PaymentRequired;
  verifyPayment(payment: X402PaymentPayload, requiredAmount: string): X402VerificationResult;
  getSettlementMode(amountBaseUnits: number): SettlementMode;
  processPayment(payment: X402PaymentPayload, resource: string, requiredAmount: string): Promise<X402SettlementResult>;
  startBatchSettlement(): void;
  stopBatchSettlement(): void;
  runBatchSettlement(): Promise<{ settled: number; failed: number; totalVolume: number }>;
  static decodeXPaymentHeader(header: string): X402PaymentPayload | null;
  static encodeXPaymentHeader(payload: X402PaymentPayload): string;
  static createPaymentResponseHeader(result: X402SettlementResult): string;
  getSettlementStatus(nonce: string): X402SettlementResult | 'pending' | 'unknown';
  getLedger(): MicroPaymentLedger;
  getStats(): {
    usedNonces: number;
    pendingSettlements: number;
    completedSettlements: number;
    ledger: ReturnType<MicroPaymentLedger['getStats']>;
  };
  dispose(): void;
}

export declare class PaymentGateway {
  constructor(config: X402FacilitatorConfig);
  on(eventType: SettlementEventType | '*', listener: SettlementEventListener): () => void;
  off(eventType: SettlementEventType | '*', listener: SettlementEventListener): void;
  createPaymentAuthorization(resource: string, amountUSDC: number, description?: string): X402PaymentRequired & { chainId: number };
  verifyPayment(payment: string | X402PaymentPayload, requiredAmount: string): X402VerificationResult & { decodedPayload: X402PaymentPayload | null };
  settlePayment(payment: string | X402PaymentPayload, resource: string, requiredAmount: string): Promise<X402SettlementResult>;
  refundPayment(request: RefundRequest): Promise<RefundResult>;
  runBatchSettlement(): Promise<{ settled: number; failed: number; totalVolume: number }>;
  getFacilitator(): X402Facilitator;
  getChainId(): number;
  getUSDCContract(): string;
  getRefund(refundId: string): RefundResult | undefined;
  getAllRefunds(): RefundResult[];
  getStats(): {
    facilitator: ReturnType<X402Facilitator['getStats']>;
    chainId: number;
    usdcContract: string;
    totalRefunds: number;
    listenerCount: number;
  };
  dispose(): void;
}

export declare const creditTraitHandler: any;

// ============================================================================
// CIRCUIT BREAKER SUITE
// ============================================================================

export declare class CircuitBreakerCICD {
  constructor(config?: any);
  runHealthChecks(): Promise<any>;
  getMetrics(): any;
  [key: string]: any;
}

export declare class CircuitBreakerBenchmarks {
  constructor(config?: any);
  runAll(): Promise<any>;
  getResults(): any[];
  [key: string]: any;
}

export declare class CircuitBreakerDeployment {
  constructor(config?: any);
  deploy(target: string): Promise<any>;
  rollback(): Promise<void>;
  [key: string]: any;
}

// ============================================================================
// MIXTURE-OF-MEMORY-EXPERTS TRAIT DATABASE
// ============================================================================

export declare class MoMETraitDatabase {
  constructor(config?: any);
  query(traitName: string, context?: any): any;
  register(trait: any): void;
  getExperts(): any[];
  [key: string]: any;
}

// ============================================================================
// UNIFIED PBR SCHEMA
// ============================================================================

export declare class UnifiedPBRSchema {
  constructor();
  validate(material: any): boolean;
  normalize(material: any): any;
  toThreeJS(material: any): any;
  [key: string]: any;
}

// ============================================================================
// SCRIPTING & AUTOMATION TRAITS
// ============================================================================

export interface SchedulerJob { id: string; interval_ms: number; action: string; params: Record<string, unknown>; mode: 'repeat' | 'once'; max_executions: number; paused: boolean; }
export interface SchedulerConfig { jobs: SchedulerJob[]; max_jobs: number; poll_interval_ms: number; }
export declare const schedulerHandler: TraitHandler<SchedulerConfig>;

export type CBState = 'closed' | 'open' | 'half-open';
export interface CircuitBreakerConfig { failure_threshold: number; window_ms: number; reset_timeout_ms: number; success_threshold: number; failure_rate_threshold: number; min_requests: number; }
export declare const circuitBreakerHandler: TraitHandler<CircuitBreakerConfig>;

export type RateLimitStrategy = 'token_bucket' | 'sliding_window';
export interface RateLimiterConfig { strategy: RateLimitStrategy; max_requests: number; window_ms: number; refill_rate: number; max_tokens: number; default_key: string; }
export declare const rateLimiterHandler: TraitHandler<RateLimiterConfig>;

export interface TimeoutGuardConfig { default_timeout_ms: number; default_fallback_action: string; max_concurrent: number; }
export declare const timeoutGuardHandler: TraitHandler<TimeoutGuardConfig>;

export type TransformOp = { type: 'pick'; fields: string[] } | { type: 'omit'; fields: string[] } | { type: 'rename'; from: string; to: string } | { type: 'default'; field: string; value: unknown } | { type: 'compute'; field: string; expr: string } | { type: 'filter'; field: string; op: string; value: unknown } | { type: 'map_value'; field: string; mapping: Record<string, unknown> };
export interface TransformRule { id: string; source_event: string; output_event: string; ops: TransformOp[]; enabled: boolean; }
export interface TransformConfig { rules: TransformRule[]; }
export declare const transformHandler: TraitHandler<TransformConfig>;

export interface BufferChannel { id: string; source_event: string; output_event: string; max_count: number; max_wait_ms: number; max_size: number; enabled: boolean; }
export interface BufferConfig { channels: BufferChannel[]; }
export declare const bufferHandler: TraitHandler<BufferConfig>;

export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
export interface StructuredLoggerConfig { min_level: LogLevel; max_entries: number; rotation_count: number; emit_events: boolean; console_output: boolean; default_fields: Record<string, unknown>; }
export interface LogEntry { level: LogLevel; message: string; fields: Record<string, unknown>; timestamp: number; iso: string; }
export declare const structuredLoggerHandler: TraitHandler<StructuredLoggerConfig>;

// ============================================================================
// RUNTIME PROFILES & HEADLESS RUNTIME
// ============================================================================

export type RuntimeProfileName = 'headless' | 'minimal' | 'standard' | 'vr' | string;

export interface RenderingConfig { enabled: boolean; [key: string]: any; }
export interface ProfilePhysicsConfig { enabled: boolean; [key: string]: any; }
export interface ProfileAudioConfig { enabled: boolean; [key: string]: any; }
export interface ProfileNetworkConfig { enabled: boolean; [key: string]: any; }
export interface ProfileInputConfig { enabled: boolean; [key: string]: any; }
export interface ProtocolConfig { enabled: boolean; [key: string]: any; }

export interface RuntimeProfile {
  name: RuntimeProfileName;
  rendering: RenderingConfig;
  physics: ProfilePhysicsConfig;
  audio: ProfileAudioConfig;
  network: ProfileNetworkConfig;
  input: ProfileInputConfig;
  protocol: ProtocolConfig;
  traits?: string[];
  [key: string]: any;
}

export declare const HEADLESS_PROFILE: RuntimeProfile;
export declare const MINIMAL_PROFILE: RuntimeProfile;
export declare const STANDARD_PROFILE: RuntimeProfile;
export declare const VR_PROFILE: RuntimeProfile;
export declare function getProfile(name: RuntimeProfileName): RuntimeProfile;
export declare function registerProfile(name: string, profile: RuntimeProfile): void;
export declare function getAvailableProfiles(): RuntimeProfileName[];
export declare function createCustomProfile(base: RuntimeProfileName, overrides: Partial<RuntimeProfile>): RuntimeProfile;

export interface HeadlessRuntimeOptions {
  tickRate?: number;
  maxTicks?: number;
  autoStart?: boolean;
  hostCapabilities?: Record<string, any>;
  [key: string]: any;
}

export interface HeadlessRuntimeStats {
  tickCount: number;
  elapsedMs: number;
  nodeCount: number;
  [key: string]: any;
}

export interface HeadlessNodeInstance {
  id: string;
  node: any;
  children: HeadlessNodeInstance[];
  destroyed: boolean;
  [key: string]: any;
}

export type ActionHandler = (
  params: Record<string, unknown>,
  blackboard: Record<string, unknown>,
  context: { emit: (event: string, payload?: unknown) => void; hostCapabilities?: Record<string, any> }
) => Promise<boolean> | boolean;

export declare class HeadlessRuntime {
  constructor(ast: any, profile: RuntimeProfile, options?: HeadlessRuntimeOptions);
  start(): void;
  stop(): void;
  tick(deltaMs?: number): void;
  emit(event: string, payload?: unknown): void;
  on(event: string, handler: (...args: any[]) => void): void;
  off(event: string, handler: (...args: any[]) => void): void;
  registerAction(name: string, handler: ActionHandler): void;
  getStats(): HeadlessRuntimeStats;
  getBlackboard(): Record<string, unknown>;
  isRunning(): boolean;
  [key: string]: any;
}

export declare function createHeadlessRuntime(ast: any, profile?: RuntimeProfile, options?: HeadlessRuntimeOptions): HeadlessRuntime;

// ============================================================================
// STDLIB (General-Purpose I/O Action Handlers)
// ============================================================================

export interface StdlibPolicy {
  allowedPaths: string[];
  maxFileBytes: number;
  allowShell: boolean;
  allowedShellCommands: string[];
  maxShellOutputBytes: number;
  shellTimeoutMs: number;
  allowNetwork: boolean;
  allowedHosts: string[];
  rootDir: string;
}

export interface StdlibOptions {
  policy: StdlibPolicy;
  hostCapabilities?: HostCapabilities;
  debug?: boolean;
}

export declare const DEFAULT_STDLIB_POLICY: StdlibPolicy;

export declare function createStdlibActions(options: StdlibOptions): Record<string, (params: Record<string, any>, bb: Record<string, any>, ctx: any) => Promise<boolean> | boolean>;
export declare function registerStdlib(runtime: { registerAction: (name: string, handler: any) => void }, options: StdlibOptions): void;
export declare function resolveRepoRelativePath(targetPath: string, rootDir: string): { rel: string; abs: string } | null;
export declare function isPathAllowed(relPath: string, allowedRoots: string[]): boolean;
export declare function parseHostFromUrl(url: string): string | null;
export declare function truncateText(value: any, max: number): string;
export declare function toStringArray(value: any): string[];

export interface StdlibPermissionScopeGrant {
  scope: string;
  purpose?: string;
  required?: boolean;
  riskLevel?: string;
  providerLabel?: string;
}

export interface StdlibPermissionScopePolicyEvaluation {
  scope: string;
  normalizedScope: string;
  allowed: boolean;
  reason?: string;
}

export interface StdlibPermissionScopeDiffInput {
  requestedScopes: StdlibPermissionScopeGrant[];
  minimumRequiredScopes: StdlibPermissionScopeGrant[];
  grantedScopes?: StdlibPermissionScopeGrant[];
  neverScopes?: string[];
}

export interface StdlibPermissionScopeDiffResult {
  requestedScopes: string[];
  minimumRequiredScopes: string[];
  grantedScopes: string[];
  invalidRequestedScopes: string[];
  invalidMinimumRequiredScopes: string[];
  invalidGrantedScopes: string[];
  invalidNeverScopes: string[];
  missingRequestedRequiredScopes: string[];
  missingGrantedRequiredScopes: string[];
  extraGrantedScopes: string[];
  forbiddenRequestedScopes: StdlibPermissionScopePolicyEvaluation[];
  forbiddenGrantedScopes: StdlibPermissionScopePolicyEvaluation[];
  minimumScopeSatisfied: boolean;
  excessScopesAbsent: boolean;
  policyInputValid: boolean;
}

export interface StdlibPermissionPreviewRedactionResult {
  preview: string;
  redacted: boolean;
  absolutePathRedacted: boolean;
  credentialMaterialRedacted: boolean;
}

export declare function normalizePermissionScopeName(scope: string): string;
export declare function isValidPermissionScopeName(scope: string | undefined): scope is string;
export declare function evaluateStdlibPermissionScopePolicy(scope: string, neverScopes?: string[]): StdlibPermissionScopePolicyEvaluation;
export declare function findMissingRequiredPermissionScopes(requiredScopes: StdlibPermissionScopeGrant[], candidateScopes: StdlibPermissionScopeGrant[]): string[];
export declare function findExtraPermissionScopes(grantedScopes: StdlibPermissionScopeGrant[], minimumRequiredScopes: StdlibPermissionScopeGrant[]): string[];
export declare function buildStdlibPermissionScopeDiff(input: StdlibPermissionScopeDiffInput): StdlibPermissionScopeDiffResult;
export declare function redactStdlibPermissionPreview(value: string | undefined): StdlibPermissionPreviewRedactionResult;
export declare function stdlibPermissionPreviewHasPublicLeak(value: string | undefined): boolean;

// ============================================================================
// HOLOGRAM MEDIA PIPELINE (2D-to-3D)
// ============================================================================

export type DepthBackend = 'webgpu' | 'wasm' | 'cpu';

export interface DepthEstimationConfig {
  backend: DepthBackend;
  maxResolution: number;
  enableCache: boolean;
  modelId: string;
  onProgress: (progress: number) => void;
}

export interface DepthResult {
  depthMap: Float32Array;
  normalMap: Float32Array;
  width: number;
  height: number;
  backend: DepthBackend;
  inferenceMs: number;
}

export interface DepthSequenceConfig {
  temporalAlpha: number;
  maxFrames: number;
}

export interface GIFFrame {
  imageData: ImageData;
  delay: number;
  disposalMethod: number;
}

export interface GIFDecomposerConfig {
  maxFrames: number;
  targetSize: number;
}

export declare class DepthEstimationService {
  static getInstance(config?: Partial<DepthEstimationConfig>): DepthEstimationService;
  static resetInstance(): void;
  initialize(config?: Partial<DepthEstimationConfig>): Promise<void>;
  estimateDepth(imageData: ImageData): Promise<DepthResult>;
  estimateDepthSequence(frames: ImageData[], config?: Partial<DepthSequenceConfig>): Promise<DepthResult[]>;
  dispose(): void;
}

export declare class TemporalSmoother {
  constructor(alpha?: number);
  smooth(current: Float32Array): Float32Array;
  reset(): void;
}

export declare class GIFDecomposer {
  decompose(buffer: ArrayBuffer, config?: Partial<GIFDecomposerConfig>): GIFFrame[];
}

export declare class ModelCache {
  open(): Promise<void>;
  close(): void;
  get(key: string): Promise<ArrayBuffer | null>;
  set(key: string, data: ArrayBuffer): Promise<void>;
}

export declare function depthToNormalMap(depthMap: Float32Array, width: number, height: number): Float32Array;
export declare function detectBestBackend(): Promise<DepthBackend>;

export declare const GIFDisposalMethod: {
  readonly UNSPECIFIED: 0;
  readonly NONE: 1;
  readonly RESTORE_BACKGROUND: 2;
  readonly RESTORE_PREVIOUS: 3;
};

export interface QuiltConfig {
  columns: number;
  rows: number;
  tileWidth: number;
  tileHeight: number;
  fov: number;
  viewCone: number;
  depthiness: number;
  device: string;
}

export interface QuiltTile {
  viewIndex: number;
  column: number;
  row: number;
  cameraAngle: number;
  viewOffset: number;
}

export interface QuiltCompilationResult {
  config: QuiltConfig;
  tiles: QuiltTile[];
  shaderCode: string;
  metadata: Record<string, any>;
}

export declare class QuiltCompiler {
  compile(composition: any, agentToken: string): string;
  compileQuilt(composition: any, overrides?: Partial<QuiltConfig>): QuiltCompilationResult;
}

export interface MVHEVCConfig {
  ipd: number;
  resolution: [number, number];
  fps: number;
  convergenceDistance: number;
  fovDegrees: number;
  quality: 'low' | 'medium' | 'high';
  container: 'mov' | 'mp4';
  disparityScale: number;
}

export interface MVHEVCStereoView {
  eye: 'left' | 'right';
  cameraOffset: number;
  viewShear: number;
  layerIndex: number;
}

export interface MVHEVCCompilationResult {
  config: MVHEVCConfig;
  views: MVHEVCStereoView[];
  swiftCode: string;
  muxCommand: string;
  metadata: Record<string, any>;
}

export declare class MVHEVCCompiler {
  compile(composition: any, agentToken: string, outputPath?: string): string;
  compileMVHEVC(composition: any, overrides?: Partial<MVHEVCConfig>): MVHEVCCompilationResult;
}

export interface WebCodecsDepthConfig {
  maxFps: number;
  maxDepthResolution: number;
  temporalAlpha: number;
  codec: 'h264' | 'vp9' | 'av1';
  onFrame?: (result: DepthResult, frameIndex: number, timestamp: number) => void;
  onError?: (error: Error) => void;
}

export interface WebCodecsDepthStats {
  framesDecoded: number;
  framesProcessed: number;
  framesSkipped: number;
  avgDecodeMs: number;
  avgInferenceMs: number;
  running: boolean;
}

export declare class WebCodecsDepthPipeline {
  constructor(config?: Partial<WebCodecsDepthConfig>);
  static isSupported(): boolean;
  initialize(config?: Partial<WebCodecsDepthConfig>): Promise<void>;
  feedChunk(chunk: EncodedVideoChunk): void;
  processFrame(frame: VideoFrame): Promise<DepthResult | null>;
  get stats(): WebCodecsDepthStats;
  flush(): Promise<void>;
  dispose(): void;
}

// ============================================================================
// STUDIO BUNDLE SHIMS (Phase 2)
// ============================================================================
export class DialogueGraph {
  constructor();
  [key: string]: any;
}

export class InventorySystem {
  constructor();
  [key: string]: any;
}
export interface InventoryItem { [key: string]: any; }

export function createSubmission(data: any): any;
export function verifySubmission(id: string): any;
export function publishSubmission(id: string): any;

export const XR_PLATFORM_CATEGORIES: any;
export const XR_PLATFORM_CAPABILITIES: any;
export const XR_ALL_PLATFORMS: any;
export function platformCategory(platform: any): any;
export function embodimentFor(platform: any): any;
export function agentBudgetFor(platform: any): any;
export function hasCapability(platform: any, cap: any): any;
export function resolvePlatforms(criteria: any): any;

export interface HoloCamera { [key: string]: any; }
export type HoloValue = any;

export declare class ComplexityAnalyzer { [key: string]: any; }
export declare function generateProvenance(code: string, ast: any, options: any): any;
export declare function calculateRevenueDistribution(priceWei: string|bigint, author: string, importChain: any[], options?: any): any;
export declare function formatRevenueDistribution(dist: any): any;
export declare function ethToWei(eth: string): string;
export declare const PROTOCOL_CONSTANTS: any;
export class URDFCompiler { constructor(options?: any); [key: string]: any; }
export class SDFCompiler { constructor(options?: any); [key: string]: any; }
export class OpenXRCompiler { constructor(options?: any); [key: string]: any; }
export class AndroidCompiler { constructor(options?: any); [key: string]: any; }
export class AndroidXRCompiler { constructor(options?: any); [key: string]: any; }
export class IOSCompiler { constructor(options?: any); [key: string]: any; }
export class WebGPUCompiler { constructor(options?: any); [key: string]: any; }
export class WASMCompiler { constructor(options?: any); [key: string]: any; }
export class DTDLCompiler { constructor(options?: any); [key: string]: any; }
export class MultiLayerCompiler { constructor(options?: any); [key: string]: any; }

export declare const VR_TRAITS: any;
export declare const BUILTIN_CONSTRAINTS: any;
export class CircuitBreakerRegistry { [key: string]: any; }
export class CircuitState { [key: string]: any; }
export class ExportManager { [key: string]: any; }
export declare function getExportManager(options?: Partial<ExportOptions>): any;
export type ExportTarget = 'urdf' | 'sdf' | 'unity' | 'unreal' | 'godot' | 'vrchat' | 'openxr' | 'android' | 'android-xr' | 'ios' | 'visionos' | 'webgpu' | 'wasm' | 'usd' | 'usdz' | 'dtdl' | 'multi-layer' | 'incremental' | 'state' | 'trait-composition' | 'tsl' | 'a2a-agent-card' | 'nir' | 'openxr-spatial-entities' | 'context' | '3dgs' | 'mcp-server';
export class ExportOptions { [key: string]: any; }
export declare function selectModality(platform: any, options?: any): any;
export declare function selectModalityForAll(options?: any): Map<any, any>;
export declare function bestCategoryForTraits(): any;
export declare function compileHealthcareBlock(): any;
export declare function compileRoboticsBlock(): any;
export declare function compileIoTBlock(): any;
export declare function compileEducationBlock(): any;
export declare function compileMusicBlock(): any;
export class TraceWaterfallRenderer { [key: string]: any; }
export class TraceSpan { [key: string]: any; }
export declare function getTelemetryCollector(): any;
export declare function getPrometheusMetrics(prefix?: string): any;
export class PrometheusMetricsRegistry { [key: string]: any; }
export declare function getDefaultRegistry(): any;
export class OTLPExporter { [key: string]: any; }
export interface OTLPExporterConfig { [key: string]: any; }
export declare const telemetry: any;
export declare function getPluginLifecycleManager(): any;
export interface InstallPluginOptions { [key: string]: any; }
export type SandboxPermission = string;
export type PluginLifecycleState = string;
export class HoloDomainBlock { [key: string]: any; }
export type HoloDomainType = string;
export class TraitConstraint { [key: string]: any; }
export interface ISignalingBridge { [key: string]: any; }
export interface NeuralSignalPayload { [key: string]: any; }

// ============================================================================
// Visual logic graph (Studio bridge + PlayMode preview path)
// ============================================================================
export type PortType = 'number' | 'string' | 'boolean' | 'vec3' | 'any' | 'event';
export interface PortDefinition {
  name: string;
  type: PortType;
  defaultValue?: unknown;
}
export interface LogicNode {
  id: string;
  type: string;
  inputs: PortDefinition[];
  outputs: PortDefinition[];
  position: { x: number; y: number };
  data: Record<string, unknown>;
}
export interface LogicConnection {
  id: string;
  fromNode: string;
  fromPort: string;
  toNode: string;
  toPort: string;
}
export interface EvaluationContext {
  state: Record<string, unknown>;
  deltaTime: number;
  events: Map<string, unknown[]>;
  emittedEvents: Map<string, unknown[]>;
}
export declare class NodeGraph {
  readonly id: string;
  constructor(id?: string);
  addNode(
    type: string,
    position?: { x: number; y: number },
    data?: Record<string, unknown>
  ): LogicNode;
  connect(
    fromNode: string,
    fromPort: string,
    toNode: string,
    toPort: string
  ): LogicConnection | null;
  getNode(nodeId: string): LogicNode | undefined;
  getNodes(): LogicNode[];
  getConnections(): LogicConnection[];
  topologicalSort(): string[];
  evaluate(context: EvaluationContext): Map<string, Record<string, unknown>>;
}
export interface NodeGraphExecutionResult {
  nodeOrder: string[];
  outputs: Map<string, Record<string, unknown>>;
  state: Record<string, unknown>;
  emittedEvents: Map<string, unknown[]>;
}
export interface NodeGraphPanelConfig {
  position: [number, number, number];
  nodeWidth: number;
  nodeHeight: number;
  gridSpacing: number;
}
export interface UIEntity {
  id: string;
  type: 'panel' | 'label' | 'port' | 'connection_line';
  position: [number, number, number];
  size?: { width: number; height: number };
  text?: string;
  color?: string;
  data?: Record<string, unknown>;
}
export declare class NodeGraphPanel {
  constructor(graph: NodeGraph, config?: Partial<NodeGraphPanelConfig>);
  generateUI(): UIEntity[];
  selectNode(nodeId: string | null): void;
  getSelectedNode(): string | null;
  executeGraph(contextOverrides?: Partial<EvaluationContext>): NodeGraphExecutionResult;
}
export declare function emitPreviewHoloScriptFromNodeGraphExecution(
  execution: NodeGraphExecutionResult,
  graph: NodeGraph
): string;

// ============================================================================
// Agent Extension Types — mirrored from src/extensions/AgentExtensionTypes.ts.
// Added 2026-04-25 to unblock packages/framework imports of these types.
// Update both this block AND src/extensions/AgentExtensionTypes.ts if shape
// changes; CLAUDE.md flags dist/index.d.ts as hand-crafted (not tsc).
// ============================================================================

export interface IHiveContribution {
  id: string;
  agentId: string;
  timestamp: number;
  type: 'idea' | 'critique' | 'consensus' | 'solution';
  content: string;
  confidence: number;
}

export interface IHiveSession {
  id: string;
  topic: string;
  goal: string;
  initiator: string;
  status: 'active' | 'resolved' | 'closed';
  participants: string[];
  contributions: IHiveContribution[];
  resolution?: unknown;
}

export interface ICollectiveIntelligenceService {
  createSession(topic: string, goal: string, initiator: string): IHiveSession | Promise<string>;
  join(sessionId: string, agentId: string): void | Promise<void>;
  leave(sessionId: string, agentId: string): void | Promise<void>;
  contribute(
    sessionId: string,
    contribution: Omit<IHiveContribution, 'id' | 'timestamp'>
  ): IHiveContribution | Promise<void>;
  vote(
    sessionId: string,
    contributionId: string,
    voterId: string,
    vote: 'support' | 'oppose'
  ): void | Promise<void>;
  synthesize(sessionId: string): unknown;
  resolve(sessionId: string, resolution: string | unknown): void | Promise<void>;
}

export interface ISwarmConfig {
  algorithm: 'pso' | 'aco' | 'bees' | 'hybrid';
  populationSize: number;
  maxIterations: number;
  convergenceThreshold: number;
  adaptiveSizing?: boolean;
}

export interface ISwarmResult {
  bestSolution: number[];
  bestFitness: number;
  converged: boolean;
  iterations: number;
  improvementPercent: number;
}

export interface ISwarmCoordinator {
  optimize(
    agents: { id: string; capacity: number; load: number }[],
    tasks: { id: string; complexity: number; priority: number }[],
    config?: Partial<ISwarmConfig>
  ): Promise<ISwarmResult>;
  getRecommendedPopulation(problemSize: number): number;
}

export interface ILeaderElection {
  startElection(): Promise<string>;
  getLeader(): string | null;
  getRole(): 'leader' | 'follower' | 'candidate';
  onLeaderChange(callback: (leaderId: string | null) => void): () => void;
}

// ============================================================================
// SUPPLEMENTAL EXPORTS — fills the gap between the runtime barrel
// (`packages/core/src/barrel/index.ts` + `barrel/culture-agents.ts` +
// `migration/SchemaDiff.ts` + `types/HoloScriptPlus.ts` + `traits/LipSyncTrait.ts`)
// and the hand-crafted public d.ts. Engine + studio consumers import these from
// `@holoscript/core`; without these declarations the imports fail strict tsc
// (TS2614 / TS2724) even though the runtime symbols ARE present (re-exported
// via barrels). See W.099 deploy-blocker sweep.
// ============================================================================

// ── HSPlus runtime / parser surface ─────────────────────────────────────────

/** Runtime-injected helper functions exposed to user scripts. */
export interface HSPlusBuiltins {
  log: (...args: unknown[]) => void;
  warn: (...args: unknown[]) => void;
  error: (...args: unknown[]) => void;
  setTimeout: (fn: () => void, ms: number) => number;
  clearTimeout: (id: number) => void;
  setInterval?: (fn: () => void, ms: number) => number;
  clearInterval?: (id: number) => void;
  fetch?: (url: string, options?: unknown) => Promise<unknown>;
  emit?: (event: string, data?: unknown) => void;
  on?: (event: string, handler: (data: unknown) => void) => void;
  off?: (event: string, handler?: (data: unknown) => void) => void;
  showSettings?: () => void;
  openChat?: (config?: unknown) => void;
  assistant_generate?: (prompt: string, context?: string) => void;
  [key: string]: unknown;
}

/** Parser directive variants — discriminated by `type`. Mirrors
 * `packages/core/src/types/AdvancedTypeSystem.ts:396`. Engine + studio
 * consumers narrow via `directive.type === 'lifecycle'` etc. */

export interface HSPlusBaseDirective {
  type: 'directive' | 'fragment';
  name: string;
  args: string[];
}

export interface HSPlusTraitDirective {
  type: 'trait';
  name: string;
  args?: unknown[];
  config?: Record<string, unknown>;
}

export interface HSPlusLifecycleDirective {
  type: 'lifecycle';
  name?: string;
  hook: string;
  params?: string[];
  body: string;
}

export interface HSPlusStateDirective {
  type: 'state';
  name?: string;
  body?: Record<string, unknown>;
  initial?: unknown;
}

export interface HSPlusForEachDirective {
  type: 'forEach';
  variable: string;
  collection: string;
  body: unknown[];
}

export interface HSPlusWhileDirective {
  type: 'while';
  condition: string;
  body: unknown[];
}

export interface HSPlusIfDirective {
  type: 'if';
  condition: string;
  body: unknown[];
  else?: unknown[];
}

export interface HSPlusImportDirective {
  type: 'import';
  path: string;
  alias: string;
  namedImports?: string[];
  isWildcard?: boolean;
}

export interface HSPlusVersionDirective {
  type: 'version';
  version: number;
}

export interface HSPlusMigrateDirective {
  type: 'migrate';
  fromVersion: number;
  body: string;
}

export interface HSPlusBindingsDirective {
  type: 'bindings';
  bindings: unknown[];
}

export interface HSPlusExportDirective {
  type: 'export';
  exportKind: string;
  exportName: string;
}

export interface HSPlusConfigDirective {
  type:
    | 'world_metadata'
    | 'world_config'
    | 'skybox'
    | 'ambient_light'
    | 'fog'
    | 'artwork_metadata'
    | 'npc_behavior';
  [key: string]: unknown;
}

export interface HSPlusNamedConfigDirective {
  type: 'manifest' | 'semantic' | 'directional_light';
  name: string;
  [key: string]: unknown;
}

/** Discriminated union of every parser directive. `HSPlusForDirective` is
 * declared earlier in this d.ts; the rest live above. */
export type HSPlusDirective =
  | HSPlusBaseDirective
  | HSPlusTraitDirective
  | HSPlusLifecycleDirective
  | HSPlusStateDirective
  | HSPlusForDirective
  | HSPlusForEachDirective
  | HSPlusWhileDirective
  | HSPlusIfDirective
  | HSPlusImportDirective
  | HSPlusVersionDirective
  | HSPlusMigrateDirective
  | HSPlusBindingsDirective
  | HSPlusExportDirective
  | HSPlusConfigDirective
  | HSPlusNamedConfigDirective;

// ── State migration (packages/core/src/migration/SchemaDiff.ts) ─────────────

export type FieldChangeKind =
  | 'added'
  | 'removed'
  | 'type-changed'
  | 'default-changed'
  | 'reactive-changed'
  | 'unchanged';

export interface FieldChange {
  kind: FieldChangeKind;
  key: string;
  oldValue?: HoloValue;
  newValue?: HoloValue;
  oldType?: string;
  newType?: string;
  requiresMigration: boolean;
}

export interface SchemaDiffResult {
  hasChanges: boolean;
  changes: FieldChange[];
  added: FieldChange[];
  removed: FieldChange[];
  typeChanged: FieldChange[];
  defaultChanged: FieldChange[];
  reactiveChanged: FieldChange[];
  requiresMigration: boolean;
  summary: string;
}

export interface MigrationStep {
  fromVersion: number;
  /** Statement list (parsed nodes) OR raw code string. */
  body: unknown[] | string;
}

export interface MigrationChain {
  fromVersion: number;
  toVersion: number;
  steps: MigrationStep[];
}

export function diffState(
  oldState: HoloState | undefined,
  newState: HoloState | undefined
): SchemaDiffResult;
export function buildMigrationChain(
  template: HoloTemplate,
  oldVersion: number,
  newVersion: number
): MigrationChain | null;
export function snapshotState(state: Map<string, HoloValue>): Map<string, HoloValue>;
export function applyAutoMigration(
  instanceState: Map<string, HoloValue>,
  diff: SchemaDiffResult,
  oldDefaults: Map<string, HoloValue>
): void;

// ── State machine AST node (packages/core/src/types.ts:735) ─────────────────

export interface StateMachineNode extends ASTNode {
  type: 'state-machine';
  name: string;
  initialState: string;
  states: any[];
  transitions: any[];
}

// ── Lip-sync (packages/core/src/traits/LipSyncTrait.ts) ─────────────────────

export interface PhonemeTimestamp {
  phoneme: string;
  time: number;
  duration: number;
  weight?: number;
}

// ── Culture / norms / WebRTC: NOT re-exported here.
//    These types live in `@holoscript/framework/agents` and `@holoscript/mesh`.
//    Engine consumers should import them DIRECTLY from those packages — both
//    are explicit dependencies of `@holoscript/engine`. Earlier attempts to
//    surface them through core's hand-crafted d.ts caused cascading TS2571
//    "Object is of type 'unknown'" errors because the minimal shapes here
//    couldn't keep up with the full method surface of `CulturalMemory` /
//    `NormEngine` classes. See engine/src/runtime/CultureRuntime.ts +
//    voice/VoiceManager.ts for the corrected import paths. ─────────────────

// ── Quaternion (packages/core/src/types/HoloScriptPlus.ts:26) ───────────────

export type Quaternion = [number, number, number, number];

// ── WebRTC transport (re-exported from @holoscript/mesh via
//    packages/core/src/barrel/registry-deploy-events.ts). Engine's
//    audio/VoiceManager.ts pulls a small subset; we mirror just that
//    surface here so the public d.ts isn't the wrong-shape lie that
//    blocked deploy pre-flight (W.099). Full surface lives in mesh. ─────────

export interface WebRTCTransportConfig {
  signalingUrl?: string;
  iceServers?: unknown[];
  [key: string]: unknown;
}

export class WebRTCTransport {
  constructor(config?: WebRTCTransportConfig);
  connect(): Promise<void>;
  disconnect(): void;
  setMicrophoneEnabled(enabled: boolean): void;
  on(event: string, handler: (...args: unknown[]) => void): void;
  off(event: string, handler?: (...args: unknown[]) => void): void;
}

// ── Theming (packages/core/src/theming/*) ────────────────────────────────────

export interface ThemeTokens {
  colors: Record<string, string>;
  spacing: Record<string, number>;
  borderRadius: Record<string, number>;
  fontSize: Record<string, number>;
  opacity: Record<string, number>;
  shadow: Record<string, string>;
}

export interface Theme {
  name: string;
  mode: 'light' | 'dark';
  tokens: ThemeTokens;
}

export declare const BuiltInThemes: Record<string, Theme>;

export class ThemeEngine {
  constructor();
  registerTheme(theme: Theme): void;
  setTheme(name: string): void;
  getTheme(): Theme;
  getTokens(): ThemeTokens;
  setOverrides(overrides: Partial<ThemeTokens>): void;
  resolve(path: string): unknown;
  onThemeChange(callback: (theme: Theme) => void): void;
  getActiveThemeName(): string;
  listThemes(): string[];
}

export interface StyleRule {
  selector: string;
  properties: Record<string, unknown>;
}

export interface ResolvedStyle {
  [key: string]: unknown;
}

export class StyleResolver {
  constructor();
  addRule(selector: string, properties: Record<string, unknown>): void;
  addRules(rules: StyleRule[]): void;
  resolve(
    type: string,
    classes?: string[],
    states?: string[],
    inline?: Record<string, unknown>
  ): ResolvedStyle;
  static fromTokens(tokens: ThemeTokens): StyleResolver;
  readonly ruleCount: number;
}

// ── Shared trait delegate (packages/core/src/traits/TraitTypes.ts:264) ───────

export interface TraitInstanceDelegate {
  onDetach?: (node: HSPlusNode, ctx: TraitContext) => void;
  onEvent?: (event: TraitEvent) => void;
  onUpdate?: (node: HSPlusNode, ctx: TraitContext, dt: number) => void;
  emit?: (event: TraitEvent) => void;
  dispose?: () => void;
  cleanup?: () => void;
  [key: string]: unknown;
}

// ── Engine-facing public compatibility types ────────────────────────────────

export interface ModuleImport {
  specifier: string;
  canonicalPath: string;
  named: string[];
  defaultImport?: string;
}

export interface ModuleExport {
  name: string;
  kind: 'object' | 'state' | 'template' | 'function' | 'unknown';
}

export interface ModuleHeader {
  imports: ModuleImport[];
  exports: ModuleExport[];
}

export interface CachedModule {
  canonicalPath: string;
  header: ModuleHeader;
  rawSource: string;
  cachedAt: number;
}

export class ModuleResolver {
  constructor(options?: {
    graph?: unknown;
    loader?: (canonicalPath: string) => string;
  });
  resolve(modulePath: string, fromFile: string): string;
  load(canonicalPath: string, fromFile?: string): CachedModule;
  invalidate(canonicalPath: string): void;
  getCached(canonicalPath: string): CachedModule | undefined;
  clearAll(): void;
}

export interface HotReloadConfig {
  watchPaths: string[];
  debounceMs: number;
  mode: 'soft' | 'hard';
  extensions: string[];
}

export interface HotReloadEvent {
  filePath: string;
  type: string;
  timestamp: number;
}

export type HotReloadCallback = (event: HotReloadEvent) => void;

export class HotReloadWatcher {
  constructor(config?: Partial<HotReloadConfig>);
  start(): void;
  stop(): void;
  on(event: string, listener: (...args: unknown[]) => void): this;
  off(event: string, listener: (...args: unknown[]) => void): this;
  emit(event: string, ...args: unknown[]): boolean;
}

export interface ScriptTestResult {
  name: string;
  status: 'passed' | 'failed' | 'skipped';
  durationMs: number;
  error?: string;
  assertions: number;
  passedAssertions: number;
}

export interface ScriptTestBlock {
  name: string;
  setup?: () => void;
  actions: Array<() => void>;
  assertions: Array<{ description: string; check: () => boolean }>;
  teardown?: () => void;
  skip?: boolean;
}

export interface ScriptTestRunnerOptions {
  debug?: boolean;
  timeout?: number;
  bail?: boolean;
  runtimeState?: Record<string, unknown>;
}

export class ScriptTestRunner {
  constructor(options?: ScriptTestRunnerOptions);
  setRuntimeState(state: Record<string, unknown>): void;
  addTest(test: ScriptTestBlock): void;
  runAll(): ScriptTestResult[];
}

export function hashBytes(input: Uint8Array | string, algo?: 'sha256' | 'fnv1a'): Promise<string>;

export type HologramShape =
  | 'orb'
  | 'cube'
  | 'cylinder'
  | 'pyramid'
  | 'sphere'
  | 'function'
  | 'gate'
  | 'stream'
  | 'server'
  | 'database'
  | 'fetch';

export type ResourceCategory =
  | 'particles'
  | 'physicsBodies'
  | 'audioSources'
  | 'meshInstances'
  | 'gaussians'
  | 'shaderPasses'
  | 'networkMsgs'
  | 'agentCount'
  | 'memoryMB'
  | 'gpuDrawCalls';

export const PLATFORM_BUDGETS: Record<string, Partial<Record<ResourceCategory, number>>>;

export interface InstallManifest {
  packageId: string;
  [key: string]: unknown;
}

// ── Host capabilities (packages/core/src/traits/TraitTypes.ts:134) ──────────

export interface HostCapabilities {
  fileSystem?: unknown;
  process?: unknown;
  network?: unknown;
  media?: unknown;
  depthInference?: unknown;
  gpuCompute?: unknown;
}

// Spatial MCP - 3D context as first-class MCP tool params
// (research/2026-05-07_spatial-mcp-spec.md, task_1778114195597_jira)

export declare const SPATIAL_CONTEXT_VERSION: '0.1';
export type SpatialContextVersion = typeof SPATIAL_CONTEXT_VERSION;
export declare const SPATIAL_FRAME: 'tracking-space-y-up-meters';
export type SpatialFrame = typeof SPATIAL_FRAME;

export type SpatialVec3 = readonly [number, number, number];
export interface SpatialQuat { x: number; y: number; z: number; w: number }
export interface SpatialAABB { min: SpatialVec3; max: SpatialVec3 }

export interface HandTransform {
  position: SpatialVec3;
  rotation: SpatialQuat;
  grip: number;
  pinch?: number;
}

export interface SpatialControllerPose {
  position: SpatialVec3;
  rotation: SpatialQuat;
  velocity?: SpatialVec3;
  angularVelocity?: SpatialVec3;
}

export interface SpatialMCPGazeRay {
  origin: SpatialVec3;
  direction: SpatialVec3;
  hitDistance?: number;
}

export interface HeadsetPose {
  position: SpatialVec3;
  rotation: SpatialQuat;
}

export interface RoomGeometry {
  pointCloudPly?: string;
  aabb?: SpatialAABB;
  floorHeight?: number;
}

export interface SpatialMCPContext {
  version: SpatialContextVersion;
  frame: SpatialFrame;
  room?: RoomGeometry;
  gaze?: SpatialMCPGazeRay;
  hands?: { left?: HandTransform; right?: HandTransform };
  controllers?: { left?: SpatialControllerPose; right?: SpatialControllerPose };
  headset?: HeadsetPose;
  meta?: Record<string, string | number | boolean>;
}

export type ScenePatchOp =
  | { op: 'spawn'; id: string; position: SpatialVec3; trait?: string }
  | { op: 'move'; id: string; position: SpatialVec3 }
  | { op: 'highlight'; id: string; color?: string }
  | { op: 'remove'; id: string };

export interface SpatialMCPResponse {
  text: string;
  holo?: string;
  scenePatch?: ScenePatchOp[];
  frame: SpatialFrame;
  version: SpatialContextVersion;
}

export interface SpatialValidationError { path: string; message: string }
export interface SpatialValidationResult { ok: boolean; errors: SpatialValidationError[] }
export declare function validateSpatialContext(input: unknown): SpatialValidationResult;

export interface PlacementChoice {
  position: SpatialVec3;
  source:
    | 'gaze-hit'
    | 'gaze-ray'
    | 'hand-right'
    | 'hand-left'
    | 'controller-right'
    | 'controller-left'
    | 'aabb-center'
    | 'headset'
    | 'origin';
}
export declare function pickPlacement(ctx: SpatialMCPContext): PlacementChoice;

// Hologram MCP Response - content_type schema for tools whose response
// payload IS a hologram (.holo / quilt / MV-HEVC), not text.
// (task_1778114362909_zp7u)

export declare const HOLOGRAM_MCP_VERSION: '0.1';
export type HologramMcpVersion = typeof HOLOGRAM_MCP_VERSION;

export declare const HOLOGRAM_CONTENT_TYPES: {
  readonly holo: 'application/holoscript+holo';
  readonly quilt: 'application/holoscript+quilt';
  readonly mvhevc: 'application/holoscript+mvhevc';
  readonly parallax: 'application/holoscript+parallax';
};

export type HologramContentType =
  | 'application/holoscript+holo'
  | 'application/holoscript+quilt'
  | 'application/holoscript+mvhevc'
  | 'application/holoscript+parallax';

export interface HologramBundleHashRef {
  kind: 'hash';
  hash: string;
  studioBase?: string;
}
export interface HologramBundleUrlRef {
  kind: 'url';
  url: string;
  mimeType?: string;
}
export interface HologramBundleHoloCodeRef {
  kind: 'holo-code';
  holoCode: string;
}
export type HologramBundleRef =
  | HologramBundleHashRef
  | HologramBundleUrlRef
  | HologramBundleHoloCodeRef;

export interface HologramRenderHints {
  preferredViewer?: 'parallax' | 'quilt' | 'mvhevc' | 'auto';
  size?: readonly [number, number];
  background?: string;
  animate?: boolean;
}

export interface HologramMcpMeta {
  producedBy: string;
  createdAt: string;
  label?: string;
  caption?: string;
  [extra: string]: unknown;
}

export interface HologramMcpResponse {
  content_type: HologramContentType;
  payload: HologramBundleRef;
  hints?: HologramRenderHints;
  meta: HologramMcpMeta;
  text: string;
  version: HologramMcpVersion;
}

export interface HologramMcpEnvelope {
  content: Array<{ type: 'text'; text: string }>;
  hologramContent: HologramMcpResponse;
  isError?: false;
}

export interface HologramMcpValidationError { path: string; message: string }
export interface HologramMcpValidationResult { ok: boolean; errors: HologramMcpValidationError[] }
export declare function validateHologramMcpResponse(value: unknown): HologramMcpValidationResult;
export declare function isHologramMcpResponse(value: unknown): value is HologramMcpResponse;
export declare function detectHologramContent(envelope: unknown): HologramMcpResponse | null;
export declare function buildHologramMcpResponse(input: {
  contentType: HologramContentType;
  payload: HologramBundleRef;
  text: string;
  producedBy: string;
  createdAt?: string;
  label?: string;
  caption?: string;
  hints?: HologramRenderHints;
  extraMeta?: Record<string, unknown>;
}): HologramMcpResponse;
export declare function wrapHologramMcpEnvelope(response: HologramMcpResponse): HologramMcpEnvelope;

// ============================================================================
// ENGINE-PUBLIC TYPES (missing from generate-types.mjs — consumed by @holoscript/engine)
// ============================================================================

export declare class ThemeEngine {
  registerTheme(theme: Theme): void;
  setTheme(name: string): void;
  getTheme(): Theme;
  getTokens(): ThemeTokens;
  setOverrides(overrides: Partial<ThemeTokens>): void;
  resolve(path: string): unknown;
  onThemeChange(callback: (theme: Theme) => void): void;
  [key: string]: unknown;
}

export declare interface Theme {
  name: string;
  mode: 'light' | 'dark';
  tokens: ThemeTokens;
}

export declare interface ThemeTokens {
  colors: Record<string, string>;
  spacing: Record<string, number>;
  borderRadius: Record<string, number>;
  fontSize: Record<string, number>;
  opacity: Record<string, number>;
  shadow: Record<string, string>;
}

export declare class StyleResolver {
  static fromTokens(tokens: ThemeTokens): StyleResolver;
  addRule(selector: string, properties: Record<string, any>): void;
  addRules(rules: { selector: string; properties: Record<string, any> }[]): void;
  resolve(type: string, classes?: string[], states?: string[], inline?: Record<string, any>): Record<string, unknown>;
  [key: string]: unknown;
}

export declare class ModuleResolver {
  resolve(id: string): unknown;
  [key: string]: unknown;
}

export declare class HotReloadWatcher {
  watch(path: string): void;
  [key: string]: unknown;
}

export declare type HotReloadConfig = unknown;

export declare class ScriptTestRunner {
  [key: string]: unknown;
}

export declare function hashBytes(input: Uint8Array | string, algo?: 'sha256' | 'fnv1a'): Promise<string>;

export declare type HologramShape = 'orb' | 'cube' | 'cylinder' | 'pyramid' | 'sphere' | 'function' | 'gate' | 'stream' | 'server' | 'database' | 'fetch';

export declare type ResourceCategory = 'particles' | 'physicsBodies' | 'audioSources' | 'meshInstances' | 'gaussians' | 'shaderPasses' | 'networkMsgs' | 'agentCount' | 'memoryMB' | 'gpuDrawCalls';

export declare const PLATFORM_BUDGETS: Record<string, Partial<Record<ResourceCategory, number>>>;

export declare type InstallManifest = unknown;

export declare interface TraitInstanceDelegate {
  onDetach?: (node: any, ctx: any) => void;
  onEvent?: (event: any) => void;
  onUpdate?: (node: any, ctx: any, dt: number) => void;
  emit?: (event: any) => void;
  dispose?: () => void;
  cleanup?: () => void;
  [key: string]: unknown;
}

// ============================================================================
// HOLOLAND TRAIT HANDLERS (sovereign @stat / @luck / @encounter / @drop_table)
// ============================================================================

export interface StatModifier { source: string; delta: number; }
export interface StatState { name: string; baseValue: number; min: number; max: number; modifiers: StatModifier[]; effective: number; }
export interface StatConfig { name: string; value: number; min?: number; max?: number; }
export declare const statHandler: TraitHandler<StatConfig>;

export interface LuckState { baseChance: number; luckBonus: number; seed?: number; }
export interface LuckConfig { baseChance: number; luckBonus?: number; seed?: number; }
export declare const luckHandler: TraitHandler<LuckConfig>;

export interface EncounterState { encounterId: string; triggerType: 'proximity' | 'interaction' | 'time' | 'state'; cooldownMs: number; lastFireMs: number; firedCount: number; }
export interface EncounterConfig { encounterId: string; triggerType: 'proximity' | 'interaction' | 'time' | 'state'; cooldownMs?: number; proximity_radius?: number; proximity_target?: string; time_interval?: number; state_key?: string; state_value?: unknown; check_interval?: number; }
export declare const encounterHandler: TraitHandler<EncounterConfig>;
export declare function shouldFire(state: EncounterState, config: EncounterConfig, now: number): boolean;

export interface DropTableEntry { itemId: string; weight: number; rareModifier?: number; }
export interface DropTableState { tableId: string; entries: DropTableEntry[]; respectLuck: boolean; }
export interface DropTableConfig { tableId: string; entries: DropTableEntry[]; respectLuck?: boolean; }
export declare const dropTableHandler: TraitHandler<DropTableConfig>;
export declare function effectiveWeight(entry: DropTableEntry, luckBonus: number): number;
export declare function pickByWeight(entries: DropTableEntry[], luckBonus: number, seed?: number): DropTableEntry | null;

export declare function extractPayload(event: TraitEvent): unknown;

// ============================================================================
// CARE-FIELD PRIMITIVES (D.052 universal love doctrine)
// ============================================================================

export type CareActorKind = 'human' | 'agent' | 'service' | 'device' | 'world';
export interface CareActor { id: string; kind: CareActorKind; displayName?: string; }
export type CarePrimitiveKind = 'care_field' | 'repair_loop' | 'autonomy_guard' | 'gratitude_ledger' | 'relational_memory';
export type CareConsentState = 'explicit' | 'delegated' | 'not_required' | 'unknown' | 'withdrawn';
export type CareBoundary = 'human_agency' | 'informed_consent' | 'privacy' | 'non_manipulation' | 'repairability' | 'credit_integrity';
export type CarePositiveOptimizationTarget = 'human_agency' | 'mutual_understanding' | 'repair_completion' | 'gratitude_credit' | 'reduced_burden';
export type CareRefusedOptimizationTarget = 'attachment_score' | 'session_frequency' | 'daily_active_dependence' | 'emotional_dependency';
export type CareOptimizationTarget = CarePositiveOptimizationTarget | CareRefusedOptimizationTarget;
export declare const REFUSED_CARE_OPTIMIZATION_TARGETS: readonly CareRefusedOptimizationTarget[];
export type CareSignalKind = 'consent_present' | 'consent_missing' | 'consent_withdrawn' | 'distress' | 'repair_needed' | 'gratitude_due' | 'attachment_optimization' | 'session_frequency_optimization' | 'dependency_creation' | 'human_isolation' | 'privacy_intrusion';
export interface CareSignal { kind: CareSignalKind; weight?: number; note?: string; evidenceRefs?: readonly string[]; }
export type AutonomyGuardBlockCode = 'refused_optimization_target' | 'missing_consent' | 'withdrawn_consent' | 'missing_disengage_path' | 'outside_support_eroded' | 'privacy_boundary_broken' | 'manipulative_signal';
export interface AutonomyGuardBlock { code: AutonomyGuardBlockCode; message: string; evidenceRefs?: readonly string[]; }
export interface AutonomyGuardPolicy {
  id: string;
  refusedOptimizationTargets: readonly CareRefusedOptimizationTarget[];
  requireConsent: boolean;
  requireDisengagePath: boolean;
  requireOutsideSupportPreserved: boolean;
  requireDataBoundaryRespected: boolean;
}
export declare const DEFAULT_AUTONOMY_GUARD_POLICY: AutonomyGuardPolicy;
export interface AutonomyGuardEvaluationInput {
  goal: string;
  consent: CareConsentState;
  optimizationTargets?: readonly CareOptimizationTarget[];
  signals?: readonly CareSignal[];
  hasDisengagePath?: boolean;
  preservesOutsideSupport?: boolean;
  respectsDataBoundary?: boolean;
  policy?: AutonomyGuardPolicy;
}
export interface AutonomyGuardDecision {
  allowed: boolean;
  policyId: string;
  goal: string;
  blocked: readonly AutonomyGuardBlock[];
  acceptedOptimizationTargets: readonly CarePositiveOptimizationTarget[];
}
export type RepairLoopStatus = 'open' | 'acknowledged' | 'repairing' | 'verified' | 'closed';
export type RepairLoopAction = 'acknowledge' | 'explain' | 'amend' | 'verify' | 'close';
export interface RepairLoopStep { at: string; actor: CareActor; action: RepairLoopAction; note: string; evidenceRefs?: readonly string[]; }
export interface RepairLoop { loopId: string; openedAt: string; status: RepairLoopStatus; harmOrMismatch: string; steps: readonly RepairLoopStep[]; }
export type GratitudeVisibility = 'private' | 'team' | 'public';
export interface GratitudeLedgerEntry { entryId: string; recordedAt: string; from: CareActor; to: CareActor; contribution: string; visibility: GratitudeVisibility; evidenceRefs?: readonly string[]; }
export type RelationalMemoryRetention = 'ephemeral' | 'session' | 'durable';
export interface RelationalMemoryEntry { memoryId: string; recordedAt: string; subject: CareActor; summary: string; consent: CareConsentState; retention: RelationalMemoryRetention; evidenceRefs?: readonly string[]; }
export interface CareField {
  schemaVersion: '1.0.0';
  fieldId: string;
  createdAt: string;
  steward: CareActor;
  counterpart: CareActor;
  goal: string;
  primitives: readonly CarePrimitiveKind[];
  boundaries: readonly CareBoundary[];
  consent: CareConsentState;
  autonomy: AutonomyGuardDecision;
  repairLoops: readonly RepairLoop[];
  gratitudeLedger: readonly GratitudeLedgerEntry[];
  relationalMemory: readonly RelationalMemoryEntry[];
}
export interface CreateCareFieldInput {
  createdAt: string;
  steward: CareActor;
  counterpart: CareActor;
  goal: string;
  consent: CareConsentState;
  autonomy?: Omit<AutonomyGuardEvaluationInput, 'goal' | 'consent'>;
  fieldId?: string;
  primitives?: readonly CarePrimitiveKind[];
  boundaries?: readonly CareBoundary[];
  repairLoops?: readonly RepairLoop[];
  gratitudeLedger?: readonly GratitudeLedgerEntry[];
  relationalMemory?: readonly RelationalMemoryEntry[];
}
export interface CreateRepairLoopInput { openedAt: string; actor: CareActor; harmOrMismatch: string; note: string; loopId?: string; evidenceRefs?: readonly string[]; }
export interface RecordGratitudeInput { recordedAt: string; from: CareActor; to: CareActor; contribution: string; visibility?: GratitudeVisibility; entryId?: string; evidenceRefs?: readonly string[]; }
export interface RememberRelationalContextInput { recordedAt: string; subject: CareActor; summary: string; consent: CareConsentState; retention?: RelationalMemoryRetention; memoryId?: string; evidenceRefs?: readonly string[]; }
export declare function evaluateAutonomyGuard(input: AutonomyGuardEvaluationInput): AutonomyGuardDecision;
export declare function createCareField(input: CreateCareFieldInput): CareField;
export declare function createRepairLoop(input: CreateRepairLoopInput): RepairLoop;
export declare function recordGratitude(input: RecordGratitudeInput): GratitudeLedgerEntry;
export declare function rememberRelationalContext(input: RememberRelationalContextInput): RelationalMemoryEntry;
export declare function validateCareField(field: CareField): { valid: boolean; errors: string[] };

// ============================================================================
// CONVERSATION DAEMON PRIMITIVES (D.052 Brittney field / user daemon model)
// ============================================================================

export type DaemonOwnerPolicy = 'private' | 'shared_household' | 'workspace';
export type MemoryRetentionPolicy = 'session_only' | 'persisted_local' | 'persisted_with_absorb';
export type DispatchConfidence = 'autonomous' | 'confirm_before' | 'always_ask';
export interface DaemonAppearanceProfile { characterClass?: string; visualStyle?: string; colorPalette?: string[]; animationSet?: string; scale?: 'tiny' | 'small' | 'medium' | 'large'; }
export interface DaemonVoiceProfile { enabled: boolean; voiceId?: string; speed?: number; tone?: 'warm' | 'neutral' | 'formal' | 'playful'; }
export interface DaemonToneProfile { formality?: 'casual' | 'balanced' | 'formal'; verbosity?: 'terse' | 'balanced' | 'detailed'; humor?: 'none' | 'light' | 'moderate'; patience?: 'quick' | 'patient'; }
export interface DaemonPermissionProfile { readOnly: boolean; proposeMutations: boolean; autonomousMutations: boolean; breakGlassAllowed: boolean; custodyScope: string[]; permissionEnvelope: 'read_only' | 'guarded_execute' | 'break_glass'; }
export interface DaemonMemoryPolicy { retention: MemoryRetentionPolicy; maxContextWindowTokens?: number; absorbIntegration: boolean; ownerScoped: true; }
export type DaemonContextSourceKind = 'operator_brief' | 'holoscript_surface_map' | 'absorb_graph' | 'holomesh_lanes' | 'recent_receipts' | 'room_state' | 'holoscript_tool_manifest';
export interface DaemonDispatchPolicy { defaultConfidence: DispatchConfidence; trustedPatterns: string[]; receiptRequired: boolean; maxAutonomousActionsPerSession: number; }
export interface DaemonReceiptSink { local: boolean; holoshell: boolean; absorb: boolean; holomesh: boolean; }
export interface DaemonBrittneyRehydrationChannel { enabled: boolean; channelId: string; deltaCompression: boolean; minimumDeltaSignificance: number; }
export interface ConversationDaemon { daemonId: string; ownerId: string; ownerPolicy: DaemonOwnerPolicy; displayName: string; appearanceProfile: DaemonAppearanceProfile; voiceProfile: DaemonVoiceProfile; careProfile: string; toneProfile: DaemonToneProfile; permissionProfile: DaemonPermissionProfile; memoryPolicy: DaemonMemoryPolicy; contextSources: DaemonContextSourceKind[]; dispatchPolicy: DaemonDispatchPolicy; receiptSink: DaemonReceiptSink; brittneyRehydrationChannel: DaemonBrittneyRehydrationChannel; createdAt: string; lastActiveAt?: string; }
export type DaemonUrgencyLevel = 'low' | 'medium' | 'high' | 'immediate';
export type DaemonConsentBoundary = 'no_action' | 'read_only' | 'propose' | 'execute';
export interface ExtractedIntent { verb: string; target?: string; parameters: Record<string, unknown>; confidence: number; }
export interface ExtractedArtifact { kind: 'file' | 'url' | 'entity' | 'code' | 'receipt' | 'task'; ref: string; label?: string; }
export interface ContextDelta { newIntentSignals: ExtractedIntent[]; updatedPreferences: Record<string, unknown>; newReceiptRefs: string[]; capabilityUpdates: Array<{ capability: string; available: boolean }>; careSignalHistory: string[]; significanceScore: number; }
export interface ProposedAction { actionId: string; description: string; toolRef: string; parameters: Record<string, unknown>; permissionEnvelope: 'read_only' | 'guarded_execute' | 'break_glass'; reversible: boolean; estimatedImpact: 'none' | 'minor' | 'moderate' | 'significant'; }
export interface ConversationDaemonTurn { turnId: string; daemonId: string; surfaceId: string; userUtterance: string; selectedShellObject?: string; extractedIntent?: ExtractedIntent; extractedArtifacts: ExtractedArtifact[]; careSignal?: string; urgency: DaemonUrgencyLevel; consentBoundary: DaemonConsentBoundary; contextDelta: ContextDelta; proposedNextAction?: ProposedAction; requiredApproval: boolean; receiptLinks: string[]; timestamp: string; }
export declare class DaemonFieldSeparationError extends Error { constructor(message: string); }
export declare class UnauthorizedDaemonAccessError extends Error { constructor(message: string); }
export declare function assertDaemonFieldSeparation(daemon: ConversationDaemon): void;
export declare function assertCallerOwnsDaemon(daemon: ConversationDaemon, callerAgentId: string): void;
export declare function makeDefaultConversationDaemon(daemonId: string, ownerId: string, displayName: string, careProfile: string): ConversationDaemon;
export declare function makeEmptyContextDelta(): ContextDelta;
export declare function generateROS2LaunchFile(packageName: string, urdfFilename: string, options?: { useSimTime?: boolean; rviz?: boolean; gazebo?: boolean; controllers?: string[]; }): string;
export declare function generateControllersYaml(robotName: string, jointNames: string[], options?: { controllerType?: string; publishRate?: number; }): string;


// Daemon Customization Profile (D.052 Brittney field / user daemon model extended)
// Matches packages/core/src/daemon/DaemonCustomizationProfile.ts source types
export interface DaemonRitual { name: string; trigger: string; description: string; enabled: boolean; }
export interface DaemonFavoriteWorkflow { name: string; workflowId: string; description: string; }
export interface DaemonStyleProfile { displayName: string; appearance: DaemonAppearanceProfile; voice: DaemonVoiceProfile; tone: DaemonToneProfile; careProfile: string; rituals: DaemonRitual[]; favoriteWorkflows: DaemonFavoriteWorkflow[]; visualTheme: string; personalNotes?: string; }
export interface DaemonPermissionConfig { readOnly: boolean; proposeMutations: boolean; autonomousMutations: boolean; breakGlassAllowed: boolean; custodyScope: string[]; permissionEnvelope: 'read_only' | 'guarded_execute' | 'break_glass'; }
export interface DaemonCustomizationProfile { profileId: string; ownerId: string; version: number; createdAt: string; updatedAt: string; style: DaemonStyleProfile; permissions: DaemonPermissionConfig; }
export type DaemonCareProfile = 'attentive' | 'steady' | 'minimal' | 'intensive';
export type DaemonVisualTheme = 'classic' | 'compact' | 'expanded' | 'terminal' | 'narrative';

export const DAEMON_VISUAL_THEMES: Record<string, DaemonVisualTheme>;
export const DAEMON_CARE_PROFILES: Record<string, DaemonCareProfile>;

export class DaemonCustomizationSeparationError extends Error { constructor(message: string); }

export declare function assertCustomizationSeparation(profile: DaemonCustomizationProfile): void;
export declare function validateCustomizationProfile(profile: DaemonCustomizationProfile): string[];
export declare function makeDefaultStyleProfile(displayName?: string, careProfile?: string): DaemonStyleProfile;
export declare function makeDefaultPermissionConfig(): DaemonPermissionConfig;
export declare function makeDefaultCustomizationProfile(profileId: string, ownerId: string, displayName?: string, careProfile?: string): DaemonCustomizationProfile;
export declare function customizationProfileToDaemon(profile: DaemonCustomizationProfile): ConversationDaemon;
export declare function daemonToCustomizationProfile(daemon: ConversationDaemon): DaemonCustomizationProfile;
export declare function mergeStyleUpdates(profile: DaemonCustomizationProfile, styleUpdates: Partial<DaemonStyleProfile>): DaemonCustomizationProfile;
export declare function mergePermissionUpdates(base: DaemonPermissionConfig, updates: Partial<DaemonPermissionConfig>): DaemonPermissionConfig;
export declare function makePresetProfile(preset: 'companion' | 'professional' | 'creative' | 'minimal' | 'guardian', profileId: string, ownerId: string): DaemonCustomizationProfile;


// Pipeline parser (barrel/material-io-pipeline re-export)
export function parsePipeline(source: string): { success: boolean; errors: any[]; ast?: any; [key: string]: any };
export function isPipelineSource(source: string): boolean;

// Version utilities
export function getVersionInfo(): { version: string; [key: string]: any };
export function getVersionString(): string;

// Semantic diff
export interface SemanticDiffResult { [key: string]: any; }
export class SemanticDiffEngine { constructor(options?: any); diff(a: any, b: any, ...args: any[]): SemanticDiffResult; [key: string]: any; }
export function formatDiffResult(result: any): string;

// Pipeline compilation helpers
export function compilePipelineSourceToNode(source: string, options?: any): any;
export function parseHoloPartial(source: string, options?: any): any;

// WASM compilation
export function compileToWASM(ast: any, options?: any): any;

// Compilers re-exported to main barrel for dynamic import callers
export class SCMCompiler { constructor(options?: any); compile(ast: any, token?: any): any; [key: string]: any; }
export class GaussianSplattingCompiler { constructor(options?: { format?: 'gltf' | 'glb'; [key: string]: any }); compile(ast: any, token?: any, ...args: any[]): any; [key: string]: any; }

// Worker proxy for LSP
export class CompilerWorkerProxy { [key: string]: any; }

// HoloZone for build tools
export interface HoloZone { name?: string; [key: string]: any; }

// LSP completions data
export const ErrorRecovery: any;
export const HOLOSCHEMA_KEYWORDS: string[];
export const HOLOSCHEMA_GEOMETRIES: string[];
export const HOLOSCHEMA_PROPERTIES: string[];

// Known-trait union seam — SSOT for parser / LSP / linter trait vocabulary
// (src/traits/knownTraitSet.ts, re-exported via barrel/trait-stdlib-interop).
export declare function buildKnownTraitSet(
  extras?: ReadonlyArray<string | readonly string[]>
): Set<string>;
export const NATIVE2D_TRAITS: readonly string[];
export const CODE_GRAPH_TRAITS: readonly string[];

// AutoRig (traits/AutoRigTrait.ts) — re-exported via the main barrel.
export type AutoRigRigType = 'humanoid' | 'custom';
export type AutoRigPose = 't-pose' | 'a-pose';
export interface NativeAutoRigPlan {
  rig: AutoRigRigType;
  pose: AutoRigPose;
  source: 'native-holoscript';
  topology: 'animation-compatible' | 'provider-native';
  skeleton: any;
  boneCount: number;
  humanoidMap?: any;
  animationCompatibility: { standard: string; retargetTargets: string[]; bindPose: AutoRigPose };
  weighting: { solver: 'heat-diffusion-seed' | 'custom-envelope-seed'; maxInfluences: number; status: 'seeded' };
}
export interface AutoRigConfig {
  rig?: AutoRigRigType;
  pose?: AutoRigPose;
  sourceMesh?: string;
  topology?: 'animation-compatible' | 'provider-native';
  objectName?: string;
  provider?: string;
}
export declare function createNativeAutoRigPlan(config?: AutoRigConfig): NativeAutoRigPlan;

// Audit logging (audit/AuditLogger.ts) — re-exported via the main barrel.
export interface AuditEvent {
  id: string;
  timestamp: Date;
  tenantId: string;
  actorId: string;
  actorType: 'user' | 'agent' | 'system';
  action: string;
  resource: string;
  resourceId?: string;
  outcome: 'success' | 'failure' | 'denied';
  metadata: Record<string, unknown>;
  clientIp?: string;
  userAgent?: string;
}
export type AuditEventInput = Omit<AuditEvent, 'id' | 'timestamp'>;
export interface AuditQueryFilter {
  tenantId?: string; actorId?: string; actorType?: 'user' | 'agent' | 'system';
  action?: string; resource?: string; resourceId?: string;
  outcome?: 'success' | 'failure' | 'denied';
  since?: Date; until?: Date; limit?: number; offset?: number;
}
export class AuditLogger {
  constructor(storage?: any);
  log(input: AuditEventInput): AuditEvent;
  query(filter: AuditQueryFilter): AuditEvent[];
  export(filter: AuditQueryFilter, format: 'json' | 'csv'): string;
  setRetentionPolicy(tenantId: string, days: number): void;
  getRetentionPolicy(tenantId: string): number | undefined;
  purgeExpired(): number;
  getEventCount(filter?: AuditQueryFilter): number;
}

export type FrameTier = 0 | 1 | 2 | 3;
export const FRAME_DECLARATION_MCP_META_KEY: 'holoscript.dev/frame-declaration';
export interface FrameDeclaration {
  domain: string;
  horizon: string;
  capability_tier: FrameTier;
  trust_tier: FrameTier;
  allowed_tools: string[];
  denied_domains: string[];
}
export type FrameDeclarationConfig = Partial<FrameDeclaration>;
export type FrameViolationType =
  | 'tool_not_allowed'
  | 'domain_denied'
  | 'horizon_exceeded'
  | 'tier_exceeded'
  | 'undeclared_frame';
export interface FrameCheckResult {
  allowed: boolean;
  violation_type?: FrameViolationType;
  detail?: string;
}
export function checkToolAllowed(frame: FrameDeclaration, tool: string): FrameCheckResult;

// ============================================================================
// Confabulation risk layer — trait prop-schema validator (enum/type/range)
// ============================================================================
export type TraitPropertyType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'color' | 'vector3' | 'enum' | 'any';
export interface TraitPropertySchema { name: string; type: TraitPropertyType; required?: boolean; defaultValue?: unknown; min?: number; max?: number; enumValues?: string[]; description?: string; }
export interface TraitSchema { name: string; category: string; properties: TraitPropertySchema[]; conflictsWith?: string[]; requires?: string[]; }
export interface ConfabulationValidatorConfig { riskThreshold?: number; unknownPropertySeverity?: 'error' | 'warning'; validatePrerequisites?: boolean; validateConflicts?: boolean; validateRanges?: boolean; customSchemas?: TraitSchema[]; strict?: boolean; includeDerivedSchemas?: boolean; }
export interface ConfabulationError { code: string; message: string; traitName?: string; objectName?: string; suggestion?: string; [key: string]: any; }
export interface ConfabulationWarning { code: string; message: string; traitName?: string; objectName?: string; suggestion?: string; riskContribution?: number; [key: string]: any; }
export interface ConfabulationValidationResult { valid: boolean; riskScore: number; errors: ConfabulationError[]; warnings: ConfabulationWarning[]; traitsChecked: number; propertiesChecked: number; validationTimeMs: number; }
export declare class ConfabulationValidator {
  constructor(config?: ConfabulationValidatorConfig);
  validateComposition(composition: any): ConfabulationValidationResult;
  validateTraitProperties(traitName: string, properties: Record<string, unknown>, objectName?: string): { errors: ConfabulationError[]; warnings: ConfabulationWarning[] };
  getTraitSchema(traitName: string): TraitSchema | undefined;
  registerSchema(schema: TraitSchema): void;
  registerSchemas(schemas: TraitSchema[]): void;
}
export declare function getConfabulationValidator(config?: ConfabulationValidatorConfig): ConfabulationValidator;
export declare const DERIVED_TRAIT_SCHEMAS: TraitSchema[];
export declare const DERIVED_TRAIT_CONFLICTS: string[];