/**
 * @holoscript/core/traits/botanical-lotus — narrow botanical trait surface
 *
 * This subpath intentionally avoids the full traits barrel because that barrel
 * imports every domain plugin. Browser renderers can use this contract without
 * bundling the entire plugin universe.
 */

export type BotanicalLotusAnchorStatus =
  | 'pending_media_ingest'
  | 'hashed'
  | 'wallet_signed';

export interface BotanicalLotusColors {
  petal_base: string;
  petal_mid: string;
  petal_inner: string;
  petal_rim: string;
  petal_shadow: string;
  seed_pod: string;
  seed_pod_rim: string;
  stamen: string;
  stamen_tip: string;
  leaf: string;
  leaf_dark: string;
  water: string;
}

export interface BotanicalLotusReferenceAnchor {
  id: string;
  label: string;
  uri: string;
  role: string;
  status: BotanicalLotusAnchorStatus;
  content_hash?: string;
  wallet_signature?: string;
  mime_type?: string;
  width?: number;
  height?: number;
}

export interface BotanicalLotusMaterial {
  subsurface_scattering: number;
  subsurface_radius_rgb: readonly [number, number, number];
  petal_translucency_base: number;
  petal_translucency_edge: number;
  roughness: number;
  ior: number;
  vein_normal_intensity: number;
  edge_curl_intensity: number;
  gravity_sag_outer: number;
  sheen: number;
  sheen_roughness: number;
  sheen_color: string;
}

export interface BotanicalLotusPetalRing {
  name: 'inner' | 'mid' | 'outer' | (string & {});
  count: number;
  cup: number;
  gravity_sag: number;
}

export interface BotanicalLotusGeometry {
  petal_rings: readonly BotanicalLotusPetalRing[];
  petal_shape: string;
  stamen_filament_count: number;
  seed_pod_dot_pattern: string;
}

export interface BotanicalLotusSource {
  kind: string;
  count: number;
  content_hash_status: BotanicalLotusAnchorStatus;
  wallet_signature_status: 'pending_cael_anchor' | 'wallet_signed';
  note: string;
}

export interface BotanicalLotusRendererHints {
  requires: readonly string[];
  lod: { close: string; mid: string; far: string };
  material_model: string;
}

export interface BotanicalLotusPlacement {
  surface_anchor_id?: string;
  surface_normal?: readonly [number, number, number];
  world_position?: readonly [number, number, number];
}

export interface BotanicalLotusLighting {
  reference_id?: string;
  estimated_lux?: number;
  color_temperature_k?: number;
  dominant_direction?: readonly [number, number, number];
}

export interface BotanicalLotusConfig {
  schema: 'holoscript.trait.botanical_lotus.v0';
  status: 'visual_seed' | 'content_hashed' | 'wallet_signed';
  source: BotanicalLotusSource;
  reference_anchors: readonly BotanicalLotusReferenceAnchor[];
  material: BotanicalLotusMaterial;
  colors: BotanicalLotusColors;
  geometry: BotanicalLotusGeometry;
  renderer: BotanicalLotusRendererHints;
}

export type BotanicalLotusConfigInput = Partial<
  Omit<BotanicalLotusConfig, 'source' | 'material' | 'colors' | 'geometry' | 'renderer'>
> & {
  source?: Partial<BotanicalLotusSource>;
  material?: Partial<BotanicalLotusMaterial>;
  colors?: Partial<BotanicalLotusColors>;
  geometry?: Partial<Omit<BotanicalLotusGeometry, 'petal_rings'>> & {
    petal_rings?: readonly BotanicalLotusPetalRing[];
  };
  renderer?: Partial<BotanicalLotusRendererHints>;
};

export interface BotanicalLotusRenderPetalRing {
  name: string;
  count: number;
  radius: number;
  length: number;
  width: number;
  cup: number;
  gravity_sag: number;
  pitch_degrees: number;
}

export interface BotanicalLotusRenderProfile {
  trait: 'botanical_lotus';
  anchor_status: BotanicalLotusAnchorStatus;
  wallet_signed: boolean;
  petal_count: number;
  petal_rings: readonly BotanicalLotusRenderPetalRing[];
  pbr_uniforms: {
    subsurface_scattering: number;
    subsurface_radius_rgb: readonly [number, number, number];
    transmission: number;
    thickness: number;
    roughness: number;
    ior: number;
    vein_normal_intensity: number;
    sheen: number;
    sheen_roughness: number;
    sheen_color: string;
  };
  colors: BotanicalLotusColors;
  stamen_filament_count: number;
  seed_pod_dot_pattern: string;
  reference_anchor_ids: readonly string[];
  renderer_requires: readonly string[];
  surface_anchor_id?: string;
  lighting_reference?: string;
}

export interface BotanicalLotusValidationResult {
  ok: boolean;
  errors: readonly string[];
  config: BotanicalLotusConfig;
}

export declare const DEFAULT_BOTANICAL_LOTUS_CONFIG: BotanicalLotusConfig;
export declare function normalizeBotanicalLotusConfig(input?: BotanicalLotusConfigInput): BotanicalLotusConfig;
export declare function validateBotanicalLotusConfig(input?: BotanicalLotusConfigInput): BotanicalLotusValidationResult;
export declare function assertBotanicalLotusConfig(input?: BotanicalLotusConfigInput): BotanicalLotusConfig;
export declare function deriveBotanicalLotusAnchorStatus(
  anchors: readonly BotanicalLotusReferenceAnchor[]
): BotanicalLotusAnchorStatus;
export declare function getBotanicalLotusPetalCount(input?: BotanicalLotusConfigInput): number;
export declare function createBotanicalLotusRenderProfile(
  input?: BotanicalLotusConfigInput,
  placement?: BotanicalLotusPlacement,
  lighting?: BotanicalLotusLighting
): BotanicalLotusRenderProfile;
export declare const botanicalLotusHandler: unknown;

// --- Scene compiler (.holo composition -> deterministic lotus scene) ---------

export type LotusBloomState = 'sealed' | 'budding' | 'blooming' | 'full' | 'wilted';

export interface LotusCompositionObject {
  name?: string;
  properties?: ReadonlyArray<{ key: string; value: unknown }>;
  traits?: ReadonlyArray<{ name: string; config?: Record<string, unknown> }>;
}

export interface LotusSceneRing {
  ring: 1 | 2 | 3;
  count: number;
  radius: number;
  length: number;
  width: number;
  cup: number;
  gravity_sag: number;
  height: number;
}

export interface LotusScenePetal {
  index: number;
  ring: 1 | 2 | 3;
  ringIndex: number;
  angle: number;
  radius: number;
  length: number;
  width: number;
  cup: number;
  gravitySag: number;
  height: number;
  color: string;
  bloom: LotusBloomState;
  label: string;
  title: string;
}

export interface LotusScene {
  seed: string;
  golden_angle_deg: number;
  growth_seconds: number;
  rings: LotusSceneRing[];
  petals: LotusScenePetal[];
  material: BotanicalLotusRenderProfile['pbr_uniforms'];
  colors: BotanicalLotusColors;
  stamen_filament_count: number;
  seed_pod_dot_pattern: string;
}

export declare const LOTUS_GOLDEN_ANGLE_DEG: number;
export declare const LOTUS_GROWTH_SECONDS: number;
export declare const LOTUS_GENESIS_SEED_PLACEHOLDER: string;
export declare const LOTUS_RING_SCALING: Record<
  1 | 2 | 3,
  { radius: number; length: number; width: number; height: number }
>;
export declare const LOTUS_OUTER_PETAL_COLOR: string;

export declare function deriveLotusBloomFromGlow(intensity: number, pulse: boolean): LotusBloomState;
export declare function lotusPetalRenderColor(
  ring: 1 | 2 | 3,
  isRoot: boolean,
  colors: BotanicalLotusColors
): string;
export declare function buildLotusSceneFromComposition(
  objects: ReadonlyArray<LotusCompositionObject>,
  profile?: BotanicalLotusRenderProfile,
  options?: { seed?: string }
): LotusScene;

export declare const LOTUS_PETAL_SHADER_CHUNKS: {
  readonly vertexHeader: string;
  readonly vertexBend: string;
  readonly vertexWorld: string;
  readonly fragmentHeader: string;
  readonly fragmentNormalInjection: string;
  readonly fragmentColorInjection: string;
  readonly fragmentEmissiveInjection: string;
};

export interface LotusShaderChunkEntry {
  stage: 'vertex' | 'fragment';
  include: string;
  code: string;
}
export declare const LOTUS_PETAL_CHUNK_ENTRIES: readonly LotusShaderChunkEntry[];
export interface LotusCompiledPhysicalProps {
  color?: string;
  roughness?: number;
  metalness?: number;
  opacity?: number;
  transparent?: boolean;
  emissive?: string;
  emissiveIntensity?: number;
  ior?: number;
  clearcoat?: number;
  clearcoatRoughness?: number;
  transmission?: number;
  thickness?: number;
  sheen?: number;
  sheenColor?: string;
  sheenRoughness?: number;
  specularIntensity?: number;
  iridescence?: number;
}
export interface LotusCompiledShaderChunkSet {
  chunks: LotusShaderChunkEntry[];
  uniforms?: Record<string, { value: unknown }>;
}
export interface LotusCompiledProceduralSpec {
  generator: string;
  params?: Record<string, unknown>;
}
export interface LotusCompiledMaterialSpec {
  physical?: LotusCompiledPhysicalProps;
  shaderChunks?: LotusCompiledShaderChunkSet;
  proceduralMaps?: {
    normalMap?: LotusCompiledProceduralSpec;
    roughnessMap?: LotusCompiledProceduralSpec;
    map?: LotusCompiledProceduralSpec;
  };
}
export interface LotusPetalDynamicUniforms {
  devTime: number;
  curlScale: number;
  growth: number;
  bloom: number;
  time: number;
}
export interface BuildLotusPetalMaterialSpecOptions {
  detailMapSize?: number;
  veinSeed?: number;
  roughnessSeed?: number;
  dynamic?: Partial<LotusPetalDynamicUniforms>;
}
export declare const LOTUS_PETAL_UNIFORM_BINDINGS: Readonly<Record<string, string>>;
export declare function buildLotusPetalMaterialSpec(
  profile: BotanicalLotusRenderProfile,
  options?: BuildLotusPetalMaterialSpecOptions
): LotusCompiledMaterialSpec;

// --- Procedural texture data (three-free; renderer wraps in DataTexture) ------

export interface ProceduralTextureData {
  width: number;
  height: number;
  data: Uint8Array;
}

export type BotanicalSurfacePattern = 'petal_veins' | 'leaf_radial' | 'stalk_fiber' | 'micro';

export declare function generateBotanicalNormalMap(opts: {
  size?: number;
  seed?: number;
  pattern: BotanicalSurfacePattern;
  strength?: number;
}): ProceduralTextureData;

export declare function generateBotanicalRoughnessMap(opts: {
  size?: number;
  seed?: number;
  base?: number;
  variance?: number;
  scale?: number;
}): ProceduralTextureData;

// --- Morphogenesis: developmental phyllotaxis simulation (grown, not placed) ---

export interface LotusPrimordium {
  index: number;
  r: number;
  theta: number;
}

export interface LotusMorphogenesisParams {
  count: number;
  seed?: number;
  apexRadius?: number;
  radialVelocity?: number;
  inhibitionExponent?: number;
  angularSamples?: number;
}

export interface LotusMorphogenesisResult {
  primordia: LotusPrimordium[];
  emergentDivergenceDeg: number;
  divergenceSpreadDeg: number;
  resolvedParams: {
    count: number;
    seed: number;
    apexRadius: number;
    radialVelocity: number;
    inhibitionExponent: number;
    angularSamples: number;
  };
}

export declare function simulateLotusMorphogenesis(
  params: LotusMorphogenesisParams
): LotusMorphogenesisResult;

export interface LotusPhyllotaxisParams {
  count: number;
  seed?: number;
  apexRadius?: number;
  radialVelocity?: number;
  inhibitorRange?: number;
  threshold?: number;
  chiralWindowDeg?: readonly [number, number];
  angularSamples?: number;
}

export interface LotusPhyllotaxisResult {
  primordia: LotusPrimordium[];
  emergentDivergenceDeg: number;
  divergenceSpreadDeg: number;
}

export declare function simulateLotusPhyllotaxis(
  params: LotusPhyllotaxisParams
): LotusPhyllotaxisResult;

export interface LotusMeristem {
  primordia: LotusPrimordium[];
  last: number;
  apexRadius: number;
  v: number;
  range: number;
  threshold: number;
  wMin: number;
  wMax: number;
  samples: number;
  step: number;
}

export declare function createLotusMeristem(params: LotusPhyllotaxisParams): LotusMeristem;
export declare function stepLotusMeristem(m: LotusMeristem): boolean;

export interface LotusPetalGrowthParams {
  developmentalTime: number;
  budCurl?: number;
  openCurl?: number;
  matureStart?: number;
  matureSpan?: number;
  acropetalDelay?: number;
  baseAngleDeg?: number;
  segments?: number;
}

export interface LotusPetalGrowthState {
  tipAngleDeg: number;
  centerline: Array<[number, number]>;
  curvature: number[];
  baseMaturity: number;
  tipMaturity: number;
}

export declare function simulateLotusPetalGrowth(
  params: LotusPetalGrowthParams
): LotusPetalGrowthState;

export interface LotusPondParams {
  size?: number;
  extent?: number;
  waveSpeed?: number;
  damping?: number;
  stalkRadius?: number;
  capillaryLength?: number;
  contactRise?: number;
}

export interface LotusPondState {
  size: number;
  extent: number;
  c: number;
  damping: number;
  dx: number;
  h: Float32Array;
  v: Float32Array;
  meniscus: Float32Array;
  mask: Float32Array;
}

export declare function createLotusPond(params?: LotusPondParams): LotusPondState;
export declare function disturbLotusPond(
  state: LotusPondState,
  worldX: number,
  worldZ: number,
  amplitude: number,
  radius?: number
): void;
export declare function stepLotusPond(state: LotusPondState, dt: number): void;
export declare function lotusPondSurface(state: LotusPondState, out?: Float32Array): Float32Array;

export interface LotusMorphogenParams {
  size?: number;
  diffusionRatio?: number;
  gamma?: number;
  a?: number;
  b?: number;
  seed?: number;
}

export interface LotusMorphogenField {
  size: number;
  d: number;
  gamma: number;
  a: number;
  b: number;
  dt: number;
  u: Float32Array;
  v: Float32Array;
}

export declare function createLotusMorphogen(params?: LotusMorphogenParams): LotusMorphogenField;
export declare function stepLotusMorphogen(field: LotusMorphogenField, iterations?: number): void;
export declare function lotusMorphogenPeaks(field: LotusMorphogenField): number;

export interface LotusMorphogen2DParams {
  size?: number;
  diffusionRatio?: number;
  gamma?: number;
  a?: number;
  b?: number;
  seed?: number;
}
export interface LotusMorphogen2DField {
  size: number;
  d: number;
  gamma: number;
  a: number;
  b: number;
  dt: number;
  u: Float32Array;
  v: Float32Array;
  mask: Uint8Array;
}
export interface LotusMorphogen2DPeak {
  x: number;
  y: number;
  radius: number;
  angle: number;
  value: number;
}
export declare function createLotusMorphogen2D(params?: LotusMorphogen2DParams): LotusMorphogen2DField;
export declare function stepLotusMorphogen2D(field: LotusMorphogen2DField, iterations?: number): void;
export declare function lotusMorphogen2DPeaks(field: LotusMorphogen2DField): LotusMorphogen2DPeak[];
export declare function lotusMorphogen2DSampleAt(field: LotusMorphogen2DField, x: number, y: number): number;

export interface LotusPetalTurgorParams {
  budCurl?: number;
  openCurl?: number;
  matureStart?: number;
  matureSpan?: number;
  acropetalDelay?: number;
  baseAngleDeg?: number;
  segments?: number;
  turgorStiffness?: number;
  turgorRise?: number;
}

export interface LotusPetalTurgorState {
  segments: number;
  baseAngle: number;
  budCurl: number;
  openCurl: number;
  matureStart: number;
  matureSpan: number;
  acropetalDelay: number;
  turgorStiffness: number;
  turgorRise: number;
  turgor: number;
  kappaActual: Float32Array;
}

export declare function createLotusPetalTurgor(params?: LotusPetalTurgorParams): LotusPetalTurgorState;
export declare function stepLotusPetalTurgor(
  state: LotusPetalTurgorState,
  dt: number,
  developmentalTime: number
): void;
export declare function lotusPetalTurgorTipDeg(state: LotusPetalTurgorState): number;
export declare function lotusPetalTurgorOpenProgress(state: LotusPetalTurgorState): number;