@almadar/ui 5.111.0 → 5.113.0

package/dist/lib/drawable/three/index.d.ts

@@ -1,39 +1,1485 @@
+import * as React$1 from 'react';
+import React__default, { Component, ReactNode, ErrorInfo } from 'react';
+import { ScenePos, EventEmit, JsonObject, OrbitalSchema } from '@almadar/core';
+import * as THREE from 'three';
+import { QuadraticBezierCurve3 } from 'three';
+import { D as DrawableNode } from '../../../paintDispatch-DR942knx.js';
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+import { I as IsometricTile, a as IsometricUnit, b as IsometricFeature, A as ApplicationLevelData, O as OrbitalLevelData, T as TraitLevelData, c as TransitionLevelData } from '../../../avl-schema-parser-B8Onmfsu.js';
+export { U as UnitAnimationState } from '../../../avl-schema-parser-B8Onmfsu.js';
+
 /**
- * The three.js VESSEL — the 3D painter backend of the drawable substrate.
- *
- * three.js is a rasterizer behind the neutral `draw-*` descriptors (the exact 3D
- * analogue of the 2D `Painter2D` seam), NOT a parallel React component tree. This
- * barrel is the SOLE entry into the R3F module graph: it is the tsup `three` entry
- * and is published behind the `@almadar/ui/components/{molecules,organisms}/game/three`
- * subpath (a STABLE alias). It is NEVER re-exported from the main `components/index.ts`
- * / `lib/index.ts` / `hooks/index.ts` barrels — that would statically pull
- * @react-three/fiber into every app's bundle. `Canvas.tsx` (the `canvas` host) lazy
- * imports this subpath for `mode:"3d"`; a 2D-only app never loads it.
- *
- * @packageDocumentation
- */
-export { Canvas3DHost, Canvas3DHost as GameCanvas3D } from './Canvas3DHost';
-export type { Canvas3DHostProps, Canvas3DHostHandle } from './Canvas3DHost';
-export { Scene3D, type Scene3DProps } from './Scene3D';
-export { Camera3D, type Camera3DProps, type Camera3DHandle, type CameraMode } from './Camera3D';
-export { Lighting3D, type Lighting3DProps } from './Lighting3D';
-export { Canvas3DLoadingState, type Canvas3DLoadingStateProps, } from './Canvas3DLoadingState';
-export { Canvas3DErrorBoundary, type Canvas3DErrorBoundaryProps, type Canvas3DErrorBoundaryState, } from './Canvas3DErrorBoundary';
-export { ModelLoader, type ModelLoaderProps, } from './ModelLoader';
-export { useThree, type UseThreeOptions, type UseThreeReturn, } from './hooks/useThree';
-export { useAssetLoader, type UseAssetLoaderOptions, type UseAssetLoaderReturn, type AssetLoadingState, } from './hooks/useAssetLoader';
-export { useSceneGraph, type UseSceneGraphReturn, type SceneGraphNode, type NodeType, } from './hooks/useSceneGraph';
-export { useRaycaster, type UseRaycasterOptions, type UseRaycasterReturn, type RaycastHit, type GridHit, } from './hooks/useRaycaster';
-export { useGameCanvas3DEvents, type UseGameCanvas3DEventsOptions, type UseGameCanvas3DEventsReturn, type GameCanvas3DEventConfig, } from './hooks/useGameCanvas3DEvents';
-export { AssetLoader, assetLoader, type LoadedModel, } from './lib/AssetLoader';
-export type { UnitAnimationState } from '../../spriteAnimationTypes';
-export { gridToWorld, worldToGrid, raycastToPlane, raycastToObjects, gridDistance, gridManhattanDistance, getNeighbors, isInBounds, getCellsInRadius, createGridHighlight, normalizeMouseCoordinates, type Grid3DConfig, type GridCoordinate, } from './lib/grid3D';
-export { isInFrustum, filterByFrustum, getVisibleIndices, calculateLODLevel, updateInstanceLOD, cullInstancedMesh, SpatialHashGrid, type CullingOptions, type LODLevel, type LODConfig, } from './lib/culling';
-export { Avl3DViewer, type Avl3DViewerProps } from '../../../components/avl/organisms/Avl3DViewer';
-export { Avl3DApplicationScene, type Avl3DApplicationSceneProps } from '../../../components/avl/organisms/Avl3DApplicationScene';
-export { Avl3DOrbitalScene, type Avl3DOrbitalSceneProps } from '../../../components/avl/organisms/Avl3DOrbitalScene';
-export { Avl3DTraitScene, type Avl3DTraitSceneProps } from '../../../components/avl/organisms/Avl3DTraitScene';
-export { Avl3DTransitionScene, type Avl3DTransitionSceneProps } from '../../../components/avl/organisms/Avl3DTransitionScene';
-export { Avl3DEffects, type Avl3DEffectsProps } from '../../../components/avl/organisms/Avl3DEffects';
-export { Avl3DContext, useAvl3DConfig, type Avl3DModelOverrides, type Avl3DConfig } from '../../../components/avl/providers/avl-3d-context';
-export { AVL_3D_COLORS, CAMERA_POSITIONS, goldenSpiralPositions, fibonacciSpherePositions, orbitRingPositions, arcCurve3D, selfLoopCurve3D, treeLayout3D, type Position3D, } from '../../../components/avl/lib/avl-3d-layout';
+ * Canvas3DHost — the thin 3D draw-host: the `canvas` host's 3D painter backend
+ * (the R3F "vessel" behind the neutral drawables), the exact 3D analogue of the
+ * 2D `Painter2D` seam. Reached only via the lazy `@almadar/ui/.../game/three`
+ * subpath so three.js never enters a 2D bundle.
+ *
+ * The 3D twin of Canvas2D: the board authors a `drawables` list (the neutral
+ * `draw-*` children) and this host maps each descriptor through `Drawable3D` to a
+ * three.js mesh (a raw descriptor NEVER reaches `<group>{children}` — R3F throws).
+ * It owns NO game data — tiles, units, features, selection, health bars and labels
+ * are all `draw-*` children composed in `.lolo`, not props here. Only view state
+ * (camera, error boundary) is local.
+ *
+ * Camera: `isometric`/`perspective`/`top-down` frame the scene bounds (derived from
+ * the drawn descriptors); `follow`/`chase` track the neutral core `Camera.target`
+ * (forwarded as `followTarget`), falling back to the scene centre.
+ *
+ * Interaction: keyboard maps to semantic events (device-agnostic input). Pointer
+ * click/hover on neutral drawables needs a per-entity id + a scene-space raycast
+ * the descriptors don't yet carry — that hit-test is a tracked fork
+ * (docs/Almadar_Std_Game_V2_PLAN.md); the click/hover event props are accepted but
+ * not yet emitted from a raycast.
+ *
+ * @packageDocumentation
+ */
+
+/** Camera mode for 3D view.
+ *  - `follow` tracks `followTarget` (the neutral `Camera.target`) from a fixed offset.
+ *  - `chase` sits behind + above the target. */
+type CameraMode$2 = 'isometric' | 'perspective' | 'top-down' | 'follow' | 'chase';
+/** Map orientation */
+type MapOrientation = 'standard' | 'rotated';
+/** Overlay control */
+type OverlayControl = 'default' | 'hidden' | 'minimap';
+/** Props for GameCanvas3D component */
+interface Canvas3DHostProps {
+    /** Additional CSS classes */
+    className?: string;
+    /** Children to render inside the 3D canvas (e.g., physics objects, custom meshes) */
+    children?: React__default.ReactNode;
+    /** Neutral drawable descriptors — the same `children` vocabulary as Canvas2D. The
+     *  host maps each through `Drawable3D` to a mesh. */
+    drawables?: DrawableNode[];
+    /** Loading state indicator */
+    isLoading?: boolean;
+    /** Error state */
+    error?: string | null;
+    /** Fog of war data (accepted for API parity; presentation-only). */
+    fogOfWar?: boolean[][];
+    /** Map orientation (data attribute). */
+    orientation?: MapOrientation;
+    /** Camera mode */
+    cameraMode?: CameraMode$2;
+    /** Follow-camera target in scene space (the neutral core `Camera.target`). */
+    followTarget?: ScenePos;
+    /** Show grid */
+    showGrid?: boolean;
+    /** Show coordinates overlay (accepted for API parity). */
+    showCoordinates?: boolean;
+    /** Show tile information (accepted for API parity). */
+    showTileInfo?: boolean;
+    /** Overlay control mode (data attribute). */
+    overlay?: OverlayControl;
+    /** Enable shadows */
+    shadows?: boolean;
+    /** Background color */
+    backgroundColor?: string;
+    /** Declarative event: tile click. Emitted from a ground-plane raycast → scene cell
+     *  `{ x, z }` (the FSM validates the cell). `tileId` is optional — the neutral host
+     *  has no per-tile id, and the board FSMs key off the coordinate. */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        z: number;
+        tileId?: string;
+        type?: string;
+        terrain?: string;
+        elevation?: number;
+    }>;
+    /** Declarative event: unit click. Emitted `{ unitId, x, z }` when the raycast lands on a
+     *  cell whose descriptor carries an `id` (a tagged unit sprite). */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+        x: number;
+        z: number;
+        unitType?: string;
+        name?: string;
+        team?: string;
+        faction?: string;
+        health?: number;
+        maxHealth?: number;
+    }>;
+    /** Declarative event: feature click. Accepted; not yet emitted (see `tileClickEvent`). */
+    featureClickEvent?: EventEmit<{
+        featureId: string;
+        x: number;
+        z: number;
+        type?: string;
+        elevation?: number;
+    }>;
+    /** Declarative event: canvas (background) click. */
+    canvasClickEvent?: EventEmit<{
+        clientX: number;
+        clientY: number;
+        button: number;
+    }>;
+    /** Declarative event: tile hover. Accepted; not yet emitted (see `tileClickEvent`). */
+    tileHoverEvent?: EventEmit<{
+        tileId: string;
+        x: number;
+        z: number;
+        type?: string;
+    }>;
+    /** Declarative event: tile leave. */
+    tileLeaveEvent?: EventEmit<Record<string, never>>;
+    /** Declarative event: unit animation. */
+    unitAnimationEvent?: EventEmit<{
+        unitId: string;
+        state: string;
+        timestamp: number;
+    }>;
+    /** Declarative event: camera change. */
+    cameraChangeEvent?: EventEmit<{
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        timestamp: number;
+    }>;
+    /** Loading message */
+    loadingMessage?: string;
+    /** Unit draw-size multiplier (accepted for API parity; sizing is drawable-authored). */
+    unitScale?: number;
+    /** Board zoom (accepted for API parity; 3D zoom is camera-driven, not group-scaled). */
+    scale?: number;
+    /** Maps a keydown `e.code` → the board's SEMANTIC event (device-agnostic input). */
+    keyMap?: Record<string, string>;
+    /** Maps a keyup `e.code` → the board's SEMANTIC event. */
+    keyUpMap?: Record<string, string>;
+    /** Side-view world size in pixels (accepted for API parity). */
+    worldWidth?: number;
+    /** Side-view world size in pixels (accepted for API parity). */
+    worldHeight?: number;
+    /** Pixel→world-unit divisor for side view (accepted for API parity). */
+    pixelsPerUnit?: number;
+}
+/** Imperative handle for GameCanvas3D */
+interface Canvas3DHostHandle {
+    /** Get current camera position */
+    getCameraPosition: () => THREE.Vector3 | null;
+    /** Set camera position */
+    setCameraPosition: (x: number, y: number, z: number) => void;
+    /** Look at a specific point */
+    lookAt: (x: number, y: number, z: number) => void;
+    /** Reset camera to default position */
+    resetCamera: () => void;
+    /** Take a screenshot */
+    screenshot: () => string | null;
+}
+/**
+ * Canvas3DHost — thin 3D draw-host. Walks `drawables` through `Drawable3D`.
+ */
+declare const Canvas3DHost: React__default.ForwardRefExoticComponent<Canvas3DHostProps & React__default.RefAttributes<Canvas3DHostHandle>>;
+
+/**
+ * Scene3D
+ *
+ * Three.js scene wrapper component for React Three Fiber.
+ * Manages the scene environment, fog, and background.
+ *
+ * @packageDocumentation
+ */
+
+interface Scene3DProps {
+    /** Background color or URL */
+    background?: string;
+    /** Fog configuration */
+    fog?: {
+        color: string;
+        near: number;
+        far: number;
+    };
+    /** Children to render in scene */
+    children?: React__default.ReactNode;
+}
+/**
+ * Scene3D Component
+ *
+ * Manages Three.js scene settings like background and fog.
+ *
+ * @example
+ * ```tsx
+ * <Canvas>
+ *     <Scene3D background="#1a1a2e" fog={{ color: '#1a1a2e', near: 10, far: 50 }}>
+ *         <GameObjects />
+ *     </Scene3D>
+ * </Canvas>
+ * ```
+ */
+declare function Scene3D({ background, fog, children }: Scene3DProps): React__default.JSX.Element;
+
+/**
+ * Camera3D
+ *
+ * Three.js camera component with orbit controls.
+ * Supports isometric, perspective, and top-down camera modes.
+ *
+ * @packageDocumentation
+ */
+
+type CameraMode$1 = 'isometric' | 'perspective' | 'top-down';
+interface Camera3DProps {
+    /** Camera mode */
+    mode?: CameraMode$1;
+    /** Initial camera position */
+    position?: [number, number, number];
+    /** Target to look at */
+    target?: [number, number, number];
+    /** Zoom level */
+    zoom?: number;
+    /** Field of view (perspective mode only) */
+    fov?: number;
+    /** Enable orbit controls */
+    enableOrbit?: boolean;
+    /** Minimum zoom distance */
+    minDistance?: number;
+    /** Maximum zoom distance */
+    maxDistance?: number;
+    /** Called when camera changes */
+    onChange?: (camera: THREE.Camera) => void;
+}
+interface Camera3DHandle {
+    /** Get current camera */
+    getCamera: () => THREE.Camera;
+    /** Set camera position */
+    setPosition: (x: number, y: number, z: number) => void;
+    /** Look at target */
+    lookAt: (x: number, y: number, z: number) => void;
+    /** Reset to initial position */
+    reset: () => void;
+    /** Get current view bounds */
+    getViewBounds: () => {
+        min: THREE.Vector3;
+        max: THREE.Vector3;
+    };
+}
+/**
+ * Camera3D Component
+ *
+ * Configurable camera with orbit controls and multiple modes.
+ *
+ * @example
+ * ```tsx
+ * <Canvas>
+ *     <Camera3D mode="isometric" position={[10, 10, 10]} target={[0, 0, 0]} />
+ * </Canvas>
+ * ```
+ */
+declare const Camera3D: React__default.ForwardRefExoticComponent<Camera3DProps & React__default.RefAttributes<Camera3DHandle>>;
+
+/**
+ * Lighting3D
+ *
+ * Default lighting setup for 3D game scenes.
+ * Includes ambient, directional, and optional point lights.
+ *
+ * @packageDocumentation
+ */
+
+interface Lighting3DProps {
+    /** Ambient light intensity */
+    ambientIntensity?: number;
+    /** Ambient light color */
+    ambientColor?: string;
+    /** Directional light intensity */
+    directionalIntensity?: number;
+    /** Directional light color */
+    directionalColor?: string;
+    /** Directional light position */
+    directionalPosition?: [number, number, number];
+    /** Enable shadows */
+    shadows?: boolean;
+    /** Shadow map size */
+    shadowMapSize?: number;
+    /** Shadow camera size (orthographic half-extent) */
+    shadowCameraSize?: number;
+    /** Shadow depth bias — reduces shadow acne */
+    shadowBias?: number;
+    /** Shadow normal bias — reduces acne on angled faces (undefined = three.js default 0) */
+    shadowNormalBias?: number;
+    /** Shadow camera near plane */
+    shadowCameraNear?: number;
+    /** Shadow camera far plane */
+    shadowCameraFar?: number;
+    /** Show helper for directional light */
+    showHelpers?: boolean;
+}
+/**
+ * Lighting3D Component
+ *
+ * Pre-configured lighting setup for game scenes.
+ *
+ * @example
+ * ```tsx
+ * <Canvas>
+ *     <Lighting3D
+ *         ambientIntensity={0.6}
+ *         directionalIntensity={1.0}
+ *         shadows={true}
+ *     />
+ * </Canvas>
+ * ```
+ */
+declare function Lighting3D({ ambientIntensity, ambientColor, directionalIntensity, directionalColor, directionalPosition, shadows, shadowMapSize, shadowCameraSize, shadowBias, shadowNormalBias, shadowCameraNear, shadowCameraFar, showHelpers, }: Lighting3DProps): React__default.JSX.Element;
+
+/**
+ * Canvas3DLoadingState
+ *
+ * Loading state component for 3D canvas with progress indicator.
+ * Displays asset loading progress and estimated time remaining.
+ *
+ * @packageDocumentation
+ */
+
+interface Canvas3DLoadingStateProps {
+    /** Current loading progress (0-100) */
+    progress?: number;
+    /** Number of assets loaded */
+    loaded?: number;
+    /** Total assets to load */
+    total?: number;
+    /** Loading message */
+    message?: string;
+    /** Secondary details message */
+    details?: string;
+    /** Whether to show spinner */
+    showSpinner?: boolean;
+    /** Custom className */
+    className?: string;
+}
+/**
+ * Canvas3DLoadingState Component
+ *
+ * Displays loading progress for 3D assets.
+ *
+ * @example
+ * ```tsx
+ * <Canvas3DLoadingState
+ *     progress={65}
+ *     loaded={13}
+ *     total={20}
+ *     message="Loading 3D models..."
+ *     details="character-knight.glb"
+ * />
+ * ```
+ */
+declare function Canvas3DLoadingState({ progress, loaded, total, message, details, showSpinner, className, }: Canvas3DLoadingStateProps): React__default.JSX.Element;
+
+/**
+ * Canvas3DErrorBoundary
+ *
+ * Error boundary for 3D canvas components.
+ * Catches Three.js and React Three Fiber errors gracefully.
+ *
+ * @packageDocumentation
+ */
+
+interface Canvas3DErrorBoundaryProps {
+    /** Child components */
+    children: ReactNode;
+    /** Custom fallback component */
+    fallback?: ReactNode;
+    /** Error callback */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    /** Reset callback */
+    onReset?: () => void;
+}
+interface Canvas3DErrorBoundaryState {
+    /** Whether an error has occurred */
+    hasError: boolean;
+    /** The error that occurred */
+    error: Error | null;
+    /** Error info from React */
+    errorInfo: ErrorInfo | null;
+}
+/**
+ * Canvas3DErrorBoundary Component
+ *
+ * Catches errors in 3D canvas and displays a user-friendly fallback.
+ *
+ * @example
+ * ```tsx
+ * <Canvas3DErrorBoundary
+ *     onError={(error) => console.error('3D Error:', error)}
+ *     onReset={() => console.log('Resetting...')}
+ * >
+ *     <GameCanvas3D {...props} />
+ * </Canvas3DErrorBoundary>
+ * ```
+ */
+declare class Canvas3DErrorBoundary extends Component<Canvas3DErrorBoundaryProps, Canvas3DErrorBoundaryState> {
+    constructor(props: Canvas3DErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): Canvas3DErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    handleReset: () => void;
+    render(): ReactNode;
+}
+
+/**
+ * ModelLoader Component
+ *
+ * React Three Fiber component for loading and displaying GLB/GLTF models from URLs.
+ * Handles loading states and errors without requiring React Suspense.
+ *
+ * @packageDocumentation
+ */
+
+interface ModelLoaderProps {
+    /** URL to the GLB/GLTF model */
+    url: string;
+    /** Position [x, y, z] */
+    position?: [number, number, number];
+    /** Scale - either a single number or [x, y, z] */
+    scale?: number | [number, number, number];
+    /** Rotation in degrees [x, y, z] */
+    rotation?: [number, number, number];
+    /** Whether the model is selected */
+    isSelected?: boolean;
+    /** Whether the model is hovered */
+    isHovered?: boolean;
+    /** Click handler */
+    onClick?: () => void;
+    /** Hover handler */
+    onHover?: (hovered: boolean) => void;
+    /** Fallback geometry type */
+    fallbackGeometry?: 'box' | 'sphere' | 'cylinder' | 'none';
+    /**
+     * Named GLB animation clip to play (e.g. "idle", "walk") — the LOLO state machine
+     * drives this from the unit's `animation` field. Matched case-insensitively; an
+     * unknown or absent name leaves the model static (bind pose).
+     */
+    animation?: string;
+    /** Multiply the model's material colors by this CSS color (per-instance; e.g. team tint). */
+    tint?: string;
+    /** Enable shadows */
+    castShadow?: boolean;
+    /** Receive shadows */
+    receiveShadow?: boolean;
+    /**
+     * Base path for shared resources (textures, materials).
+     * If not provided, auto-detected from the URL by looking for a `/3d/` segment.
+     * E.g. "https://host/3d/" so that "Textures/colormap.png" resolves correctly.
+     */
+    resourceBasePath?: string;
+}
+/**
+ * ModelLoader component for rendering GLB models in React Three Fiber
+ */
+declare function ModelLoader({ url, position, scale, rotation, isSelected, isHovered, onClick, onHover, fallbackGeometry, castShadow, receiveShadow, resourceBasePath, animation, tint, }: ModelLoaderProps): React__default.JSX.Element;
+
+/**
+ * AssetLoader
+ *
+ * Three.js asset loading manager for 3D models and textures.
+ * Supports GLB/GLTF (primary), OBJ (fallback), and texture loading.
+ * Implements caching for performance.
+ *
+ * @packageDocumentation
+ */
+
+interface LoadedModel {
+    scene: THREE.Group;
+    animations: THREE.AnimationClip[];
+}
+declare class AssetLoader {
+    private objLoader;
+    private textureLoader;
+    private modelCache;
+    private textureCache;
+    private loadingPromises;
+    constructor();
+    /**
+     * Load a GLB/GLTF model
+     * @param url - URL to the .glb or .gltf file
+     * @returns Promise with loaded model scene and animations
+     */
+    loadModel(url: string): Promise<LoadedModel>;
+    /**
+     * Load an OBJ model (fallback for non-GLB assets)
+     * @param url - URL to the .obj file
+     * @returns Promise with loaded object group
+     */
+    loadOBJ(url: string): Promise<THREE.Group>;
+    /**
+     * Load a texture
+     * @param url - URL to the texture image
+     * @returns Promise with loaded texture
+     */
+    loadTexture(url: string): Promise<THREE.Texture>;
+    /**
+     * Preload multiple assets
+     * @param urls - Array of asset URLs to preload
+     * @returns Promise that resolves when all assets are loaded
+     */
+    preload(urls: string[]): Promise<void>;
+    /**
+     * Check if a model is cached
+     * @param url - Model URL
+     */
+    hasModel(url: string): boolean;
+    /**
+     * Check if a texture is cached
+     * @param url - Texture URL
+     */
+    hasTexture(url: string): boolean;
+    /**
+     * Get cached model (throws if not cached)
+     * @param url - Model URL
+     */
+    getModel(url: string): LoadedModel;
+    /**
+     * Get cached texture (throws if not cached)
+     * @param url - Texture URL
+     */
+    getTexture(url: string): THREE.Texture;
+    /**
+     * Clear all caches
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        models: number;
+        textures: number;
+        loading: number;
+    };
+}
+declare const assetLoader: AssetLoader;
+
+type CameraMode = 'isometric' | 'perspective' | 'top-down';
+interface UseThreeOptions {
+    /** Camera mode for viewing the scene */
+    cameraMode?: CameraMode;
+    /** Initial camera position [x, y, z] */
+    cameraPosition?: [number, number, number];
+    /** Background color */
+    backgroundColor?: string;
+    /** Enable shadows */
+    shadows?: boolean;
+    /** Enable grid helper */
+    showGrid?: boolean;
+    /** Grid size */
+    gridSize?: number;
+    /** Asset loader instance */
+    assetLoader?: AssetLoader;
+}
+interface UseThreeReturn {
+    /** Canvas element reference (for React Three Fiber) */
+    canvasRef: React.RefObject<HTMLCanvasElement | null>;
+    /** Three.js renderer */
+    renderer: THREE.WebGLRenderer | null;
+    /** Three.js scene */
+    scene: THREE.Scene | null;
+    /** Three.js camera */
+    camera: THREE.Camera | null;
+    /** Orbit controls */
+    controls: OrbitControls | null;
+    /** Is scene ready */
+    isReady: boolean;
+    /** Canvas dimensions */
+    dimensions: {
+        width: number;
+        height: number;
+    };
+    /** Set camera position */
+    setCameraPosition: (x: number, y: number, z: number) => void;
+    /** Look at a specific point */
+    lookAt: (x: number, y: number, z: number) => void;
+    /** Reset camera to initial position */
+    resetCamera: () => void;
+    /** Fit view to bounds */
+    fitView: (bounds: {
+        minX: number;
+        maxX: number;
+        minZ: number;
+        maxZ: number;
+    }) => void;
+}
+/**
+ * Hook for managing a Three.js scene
+ * This is a lower-level hook used by GameCanvas3D
+ */
+declare function useThree(options?: UseThreeOptions): UseThreeReturn;
+
+interface UseAssetLoaderOptions {
+    /** URLs to preload on mount */
+    preloadUrls?: string[];
+    /** Asset loader instance (uses singleton if not provided) */
+    loader?: AssetLoader;
+}
+interface AssetLoadingState {
+    /** Whether assets are currently loading */
+    isLoading: boolean;
+    /** Loading progress (0-100) */
+    progress: number;
+    /** Number of loaded assets */
+    loaded: number;
+    /** Total assets to load */
+    total: number;
+    /** Any loading errors */
+    errors: string[];
+}
+interface UseAssetLoaderReturn extends AssetLoadingState {
+    /** Load a single model */
+    loadModel: (url: string) => Promise<LoadedModel>;
+    /** Load a single OBJ model */
+    loadOBJ: (url: string) => Promise<THREE.Group>;
+    /** Load a single texture */
+    loadTexture: (url: string) => Promise<THREE.Texture>;
+    /** Preload multiple assets */
+    preload: (urls: string[]) => Promise<void>;
+    /** Check if model is cached */
+    hasModel: (url: string) => boolean;
+    /** Check if texture is cached */
+    hasTexture: (url: string) => boolean;
+    /** Get cached model */
+    getModel: (url: string) => LoadedModel | undefined;
+    /** Get cached texture */
+    getTexture: (url: string) => THREE.Texture | undefined;
+    /** Clear all caches */
+    clearCache: () => void;
+}
+/**
+ * Hook for managing 3D asset loading in React components
+ *
+ * @example
+ * ```tsx
+ * const { loadModel, isLoading, progress } = useAssetLoader({
+ *     preloadUrls: ['/assets/model.glb']
+ * });
+ *
+ * useEffect(() => {
+ *     loadModel('/assets/character.glb').then((model) => {
+ *         scene.add(model.scene);
+ *     });
+ * }, []);
+ * ```
+ */
+declare function useAssetLoader(options?: UseAssetLoaderOptions): UseAssetLoaderReturn;
+
+type NodeType = 'tile' | 'unit' | 'feature' | 'highlight' | 'effect';
+interface SceneGraphNode {
+    /** Unique node identifier */
+    id: string;
+    /** Node type classification */
+    type: NodeType;
+    /** Three.js object */
+    mesh: THREE.Object3D;
+    /** World position */
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Grid position */
+    gridPosition: {
+        x: number;
+        z: number;
+    };
+    /** Optional metadata */
+    metadata?: JsonObject;
+}
+interface UseSceneGraphReturn {
+    /** Reference to the nodes map */
+    nodesRef: React.MutableRefObject<Map<string, SceneGraphNode>>;
+    /** Add a node to the scene */
+    addNode: (node: SceneGraphNode) => void;
+    /** Remove a node from the scene */
+    removeNode: (id: string) => void;
+    /** Get a node by ID */
+    getNode: (id: string) => SceneGraphNode | undefined;
+    /** Update node position */
+    updateNodePosition: (id: string, x: number, y: number, z: number) => void;
+    /** Update node grid position */
+    updateNodeGridPosition: (id: string, gridX: number, gridZ: number) => void;
+    /** Get node at grid position */
+    getNodeAtGrid: (x: number, z: number, type?: NodeType) => SceneGraphNode | undefined;
+    /** Get all nodes of a specific type */
+    getNodesByType: (type: NodeType) => SceneGraphNode[];
+    /** Get all nodes within a bounding box */
+    getNodesInBounds: (minX: number, maxX: number, minZ: number, maxZ: number) => SceneGraphNode[];
+    /** Clear all nodes */
+    clearNodes: () => void;
+    /** Count nodes by type */
+    countNodes: (type?: NodeType) => number;
+}
+/**
+ * Hook for managing the 3D scene graph
+ *
+ * @example
+ * ```tsx
+ * const { addNode, removeNode, getNodeAtGrid } = useSceneGraph();
+ *
+ * // Add a tile
+ * addNode({
+ *     id: 'tile-0-0',
+ *     type: 'tile',
+ *     mesh: tileMesh,
+ *     position: { x: 0, y: 0, z: 0 },
+ *     gridPosition: { x: 0, z: 0 }
+ * });
+ * ```
+ */
+declare function useSceneGraph(): UseSceneGraphReturn;
+
+interface RaycastHit {
+    /** Intersected object */
+    object: THREE.Object3D;
+    /** Intersection point */
+    point: THREE.Vector3;
+    /** Distance from camera */
+    distance: number;
+    /** UV coordinates (if available) */
+    uv?: THREE.Vector2;
+    /** Face normal */
+    face?: THREE.Face;
+    /** Face index */
+    faceIndex?: number;
+    /** Instance ID (for instanced meshes) */
+    instanceId?: number;
+}
+interface GridHit {
+    /** Grid X coordinate */
+    gridX: number;
+    /** Grid Z coordinate */
+    gridZ: number;
+    /** World position */
+    worldPosition: THREE.Vector3;
+    /** Intersected object type */
+    objectType?: 'tile' | 'unit' | 'feature';
+    /** Object ID if available */
+    objectId?: string;
+}
+interface UseRaycasterOptions {
+    /** Camera reference */
+    camera: THREE.Camera | null;
+    /** Canvas element for coordinate conversion */
+    canvas: HTMLCanvasElement | null;
+    /** Grid cell size */
+    cellSize?: number;
+    /** Grid offset X */
+    offsetX?: number;
+    /** Grid offset Z */
+    offsetZ?: number;
+}
+interface UseRaycasterReturn {
+    /** Raycaster instance */
+    raycaster: React.MutableRefObject<THREE.Raycaster>;
+    /** Mouse vector instance */
+    mouse: React.MutableRefObject<THREE.Vector2>;
+    /** Get intersection at client coordinates */
+    getIntersection: (clientX: number, clientY: number, objects: THREE.Object3D[]) => RaycastHit | null;
+    /** Get all intersections at client coordinates */
+    getAllIntersections: (clientX: number, clientY: number, objects: THREE.Object3D[]) => RaycastHit[];
+    /** Get grid coordinates at client position */
+    getGridCoordinates: (clientX: number, clientY: number) => {
+        x: number;
+        z: number;
+    } | null;
+    /** Get tile at client position from scene */
+    getTileAtPosition: (clientX: number, clientY: number, scene: THREE.Scene) => GridHit | null;
+    /** Convert client coordinates to normalized device coordinates */
+    clientToNDC: (clientX: number, clientY: number) => {
+        x: number;
+        y: number;
+    };
+    /** Check if point is within canvas bounds */
+    isWithinCanvas: (clientX: number, clientY: number) => boolean;
+}
+/**
+ * Hook for 3D raycasting operations
+ *
+ * @example
+ * ```tsx
+ * const { getIntersection, getGridCoordinates } = useRaycaster({
+ *     camera,
+ *     canvas: canvasRef.current
+ * });
+ *
+ * const handleClick = (e: MouseEvent) => {
+ *     const hit = getIntersection(e.clientX, e.clientY, tileMeshes);
+ *     if (hit) {
+ *         const grid = getGridCoordinates(e.clientX, e.clientY);
+ *         console.log('Clicked grid:', grid);
+ *     }
+ * };
+ * ```
+ */
+declare function useRaycaster(options: UseRaycasterOptions): UseRaycasterReturn;
+
+interface GameCanvas3DEventConfig {
+    /** Event name for tile clicks. `tileId` is optional — the neutral draw-host emits
+     *  only the scene coordinate `{ x, z }` (the FSM keys off the cell, not an id). */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        z: number;
+        tileId?: string;
+        type?: string;
+        terrain?: string;
+        elevation?: number;
+    }>;
+    /** Event name for unit clicks */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+        x: number;
+        z: number;
+        unitType?: string;
+        name?: string;
+        team?: string;
+        faction?: string;
+        health?: number;
+        maxHealth?: number;
+    }>;
+    /** Event name for feature clicks */
+    featureClickEvent?: EventEmit<{
+        featureId: string;
+        x: number;
+        z: number;
+        type?: string;
+        elevation?: number;
+    }>;
+    /** Event name for canvas clicks */
+    canvasClickEvent?: EventEmit<{
+        clientX: number;
+        clientY: number;
+        button: number;
+    }>;
+    /** Event name for tile hover */
+    tileHoverEvent?: EventEmit<{
+        tileId: string;
+        x: number;
+        z: number;
+        type?: string;
+    }>;
+    /** Event name for tile leave */
+    tileLeaveEvent?: EventEmit<Record<string, never>>;
+    /** Event name for unit animation changes */
+    unitAnimationEvent?: EventEmit<{
+        unitId: string;
+        state: string;
+        timestamp: number;
+    }>;
+    /** Event name for camera changes */
+    cameraChangeEvent?: EventEmit<{
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        timestamp: number;
+    }>;
+}
+/** Minimal mouse event interface — satisfied by both React.MouseEvent and ThreeEvent<MouseEvent> */
+interface MinimalMouseEvent {
+    clientX: number;
+    clientY: number;
+    button: number;
+}
+interface UseGameCanvas3DEventsOptions extends GameCanvas3DEventConfig {
+    /** Callback for tile clicks (direct) */
+    onTileClick?: (tile: IsometricTile, event: MinimalMouseEvent) => void;
+    /** Callback for unit clicks (direct) */
+    onUnitClick?: (unit: IsometricUnit, event: MinimalMouseEvent) => void;
+    /** Callback for feature clicks (direct) */
+    onFeatureClick?: (feature: IsometricFeature, event: MinimalMouseEvent) => void;
+    /** Callback for canvas clicks (direct) */
+    onCanvasClick?: (event: MinimalMouseEvent) => void;
+    /** Callback for tile hover (direct) */
+    onTileHover?: (tile: IsometricTile | null, event: MinimalMouseEvent) => void;
+    /** Callback for unit animation changes (direct) */
+    onUnitAnimation?: (unitId: string, state: string) => void;
+}
+interface UseGameCanvas3DEventsReturn {
+    /** Handle tile click - emits event and calls callback */
+    handleTileClick: (tile: IsometricTile, event: MinimalMouseEvent) => void;
+    /** Handle unit click - emits event and calls callback */
+    handleUnitClick: (unit: IsometricUnit, event: MinimalMouseEvent) => void;
+    /** Handle feature click - emits event and calls callback */
+    handleFeatureClick: (feature: IsometricFeature, event: MinimalMouseEvent) => void;
+    /** Handle canvas click - emits event and calls callback */
+    handleCanvasClick: (event: MinimalMouseEvent) => void;
+    /** Handle tile hover - emits event and calls callback */
+    handleTileHover: (tile: IsometricTile | null, event: MinimalMouseEvent) => void;
+    /** Handle unit animation - emits event and calls callback */
+    handleUnitAnimation: (unitId: string, state: string) => void;
+    /** Handle camera change - emits event */
+    handleCameraChange: (position: {
+        x: number;
+        y: number;
+        z: number;
+    }) => void;
+}
+/**
+ * Hook for integrating GameCanvas3D with the event bus
+ *
+ * Supports both declarative event props (tileClickEvent) and
+ * direct callback props (onTileClick).
+ *
+ * @example
+ * ```tsx
+ * const events = useGameCanvas3DEvents({
+ *     tileClickEvent: 'TILE_SELECTED',
+ *     unitClickEvent: 'UNIT_SELECTED',
+ *     onTileClick: (tile) => console.log('Tile:', tile)
+ * });
+ *
+ * // In component:
+ * <TileRenderer onTileClick={events.handleTileClick} />
+ * ```
+ */
+declare function useGameCanvas3DEvents(options: UseGameCanvas3DEventsOptions): UseGameCanvas3DEventsReturn;
+
+/**
+ * Grid 3D Utilities
+ *
+ * Utility functions for 3D grid coordinate transformations,
+ * raycasting, and spatial calculations for GameCanvas3D.
+ *
+ * @packageDocumentation
+ */
+
+interface Grid3DConfig {
+    /** Size of each grid cell */
+    cellSize: number;
+    /** Grid offset X */
+    offsetX?: number;
+    /** Grid offset Z */
+    offsetZ?: number;
+    /** Grid Y height (elevation) */
+    elevation?: number;
+}
+interface GridCoordinate {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Convert grid coordinates to world position
+ * @param gridX - Grid X coordinate
+ * @param gridZ - Grid Z coordinate
+ * @param config - Grid configuration
+ * @returns World position vector
+ */
+declare function gridToWorld(gridX: number, gridZ: number, config?: Grid3DConfig): THREE.Vector3;
+/**
+ * Convert world position to grid coordinates
+ * @param worldX - World X position
+ * @param worldZ - World Z position
+ * @param config - Grid configuration
+ * @returns Grid coordinates
+ */
+declare function worldToGrid(worldX: number, worldZ: number, config?: Grid3DConfig): {
+    x: number;
+    z: number;
+};
+/**
+ * Raycast from camera through mouse position to find grid intersection
+ * @param camera - Three.js camera
+ * @param mouseX - Mouse X position (normalized -1 to 1)
+ * @param mouseY - Mouse Y position (normalized -1 to 1)
+ * @param planeY - Y height of the intersection plane (default: 0)
+ * @returns Intersection point or null
+ */
+declare function raycastToPlane(camera: THREE.Camera, mouseX: number, mouseY: number, planeY?: number): THREE.Vector3 | null;
+/**
+ * Raycast from camera through mouse position against a set of objects
+ * @param camera - Three.js camera
+ * @param mouseX - Mouse X position (normalized -1 to 1)
+ * @param mouseY - Mouse Y position (normalized -1 to 1)
+ * @param objects - Array of objects to test
+ * @returns First intersection or null
+ */
+declare function raycastToObjects(camera: THREE.Camera, mouseX: number, mouseY: number, objects: THREE.Object3D[]): THREE.Intersection | null;
+/**
+ * Calculate distance between two grid coordinates
+ * @param a - First grid coordinate
+ * @param b - Second grid coordinate
+ * @returns Distance in grid units
+ */
+declare function gridDistance(a: {
+    x: number;
+    z: number;
+}, b: {
+    x: number;
+    z: number;
+}): number;
+/**
+ * Calculate Manhattan distance between two grid coordinates
+ * @param a - First grid coordinate
+ * @param b - Second grid coordinate
+ * @returns Manhattan distance
+ */
+declare function gridManhattanDistance(a: {
+    x: number;
+    z: number;
+}, b: {
+    x: number;
+    z: number;
+}): number;
+/**
+ * Get neighboring grid cells
+ * @param x - Center X coordinate
+ * @param z - Center Z coordinate
+ * @param includeDiagonal - Whether to include diagonal neighbors
+ * @returns Array of neighbor coordinates
+ */
+declare function getNeighbors(x: number, z: number, includeDiagonal?: boolean): {
+    x: number;
+    z: number;
+}[];
+/**
+ * Check if a grid coordinate is within bounds
+ * @param x - X coordinate
+ * @param z - Z coordinate
+ * @param bounds - Bounds object
+ * @returns Whether the coordinate is within bounds
+ */
+declare function isInBounds(x: number, z: number, bounds: {
+    minX: number;
+    maxX: number;
+    minZ: number;
+    maxZ: number;
+}): boolean;
+/**
+ * Get all grid cells within a circular radius
+ * @param centerX - Center X coordinate
+ * @param centerZ - Center Z coordinate
+ * @param radius - Radius in grid units
+ * @returns Array of coordinates within radius
+ */
+declare function getCellsInRadius(centerX: number, centerZ: number, radius: number): {
+    x: number;
+    z: number;
+}[];
+/**
+ * Create a highlight mesh for grid cells
+ * @param color - Highlight color
+ * @param opacity - Opacity (0-1)
+ * @returns Mesh that can be positioned at grid cells
+ */
+declare function createGridHighlight(color?: number, opacity?: number): THREE.Mesh;
+/**
+ * Normalize mouse coordinates to NDC (-1 to 1)
+ * @param clientX - Mouse client X
+ * @param clientY - Mouse client Y
+ * @param element - Canvas element
+ * @returns Normalized coordinates
+ */
+declare function normalizeMouseCoordinates(clientX: number, clientY: number, element: HTMLElement): {
+    x: number;
+    y: number;
+};
+
+/**
+ * Culling Utilities
+ *
+ * Frustum culling and LOD (Level of Detail) management for 3D scene optimization.
+ *
+ * @packageDocumentation
+ */
+
+interface CullingOptions {
+    /** Camera frustum for culling */
+    camera: THREE.Camera;
+    /** Optional padding around frustum */
+    padding?: number;
+}
+interface LODLevel {
+    /** Distance threshold for this LOD level */
+    distance: number;
+    /** Geometry or mesh for this level */
+    geometry?: THREE.BufferGeometry;
+    /** Scale multiplier for this level */
+    scale?: number;
+    /** Whether to use simplified material */
+    simpleMaterial?: boolean;
+}
+interface LODConfig {
+    /** LOD levels from closest to farthest */
+    levels: LODLevel[];
+    /** Transition smoothness (0-1) */
+    transitionSmoothness?: number;
+}
+/**
+ * Frustum culling check for a position
+ * @param position - World position to check
+ * @param camera - Camera to check against
+ * @param padding - Optional padding in world units
+ * @returns Whether the position is within the frustum
+ */
+declare function isInFrustum(position: THREE.Vector3, camera: THREE.Camera, padding?: number): boolean;
+/**
+ * Filter an array of positions to only those within the frustum
+ * @param positions - Array of world positions
+ * @param camera - Camera to check against
+ * @param padding - Optional padding in world units
+ * @returns Array of positions within frustum
+ */
+declare function filterByFrustum(positions: THREE.Vector3[], camera: THREE.Camera, padding?: number): THREE.Vector3[];
+/**
+ * Get indices of visible items from an array
+ * @param positions - Array of world positions
+ * @param camera - Camera to check against
+ * @param padding - Optional padding in world units
+ * @returns Set of visible indices
+ */
+declare function getVisibleIndices(positions: THREE.Vector3[], camera: THREE.Camera, padding?: number): Set<number>;
+/**
+ * Calculate LOD level based on distance from camera
+ * @param position - Object position
+ * @param camera - Camera position
+ * @param lodLevels - Array of distance thresholds (sorted closest to farthest)
+ * @returns Index of the LOD level to use
+ */
+declare function calculateLODLevel(position: THREE.Vector3, camera: THREE.Camera, lodLevels: number[]): number;
+/**
+ * Create a distance-based LOD system for an instanced mesh
+ * @param instancedMesh - The instanced mesh to manage
+ * @param positions - Array of instance positions
+ * @param camera - Camera to calculate distances from
+ * @param lodDistances - Distance thresholds for LOD levels
+ * @returns Array of LOD indices for each instance
+ */
+declare function updateInstanceLOD(instancedMesh: THREE.InstancedMesh, positions: THREE.Vector3[], camera: THREE.Camera, lodDistances: number[]): Uint8Array;
+/**
+ * Create visibility data for instanced mesh culling
+ * Updates the instance matrix to hide/show instances
+ * @param instancedMesh - The instanced mesh
+ * @param positions - Array of instance positions
+ * @param visibleIndices - Set of visible indices
+ * @returns Updated count of visible instances
+ */
+declare function cullInstancedMesh(instancedMesh: THREE.InstancedMesh, positions: THREE.Vector3[], visibleIndices: Set<number>): number;
+/**
+ * Spatial hash grid for efficient object queries
+ */
+declare class SpatialHashGrid {
+    private cellSize;
+    private cells;
+    private objectPositions;
+    constructor(cellSize?: number);
+    /**
+     * Get cell key for a position
+     */
+    private getCellKey;
+    /**
+     * Insert an object into the grid
+     */
+    insert(id: string, position: THREE.Vector3): void;
+    /**
+     * Remove an object from the grid
+     */
+    remove(id: string): void;
+    /**
+     * Update an object's position
+     */
+    update(id: string, newPosition: THREE.Vector3): void;
+    /**
+     * Query objects within a radius of a position
+     */
+    queryRadius(center: THREE.Vector3, radius: number): string[];
+    /**
+     * Query objects within a bounding box
+     */
+    queryBox(minX: number, maxX: number, minZ: number, maxZ: number): string[];
+    /**
+     * Clear all objects from the grid
+     */
+    clear(): void;
+    /**
+     * Get statistics about the grid
+     */
+    getStats(): {
+        objects: number;
+        cells: number;
+    };
+}
+
+/**
+ * AVL Cosmic Zoom State Machine
+ *
+ * useReducer-based state machine managing which zoom level is displayed,
+ * what is selected, and animation state.
+ *
+ * Shared by AvlOrbitalsCosmicZoom (2D) and Avl3DViewer (3D). The 3D
+ * viewer drills through every level (`application → orbital → trait →
+ * transition`); the 2D cosmic view skips the `'orbital'` level after
+ * COSMIC-1 (no Orbital-View screen) by dispatching `JUMP_TO_TRAIT_CIRCUIT`
+ * to land directly at `'trait'`.
+ *
+ * @packageDocumentation
+ */
+type ZoomLevel = 'application' | 'orbital' | 'trait' | 'transition';
+
+/**
+ * avl-3d-context.ts
+ *
+ * React context for AVL 3D model overrides and configuration.
+ * Allows replacing primitive geometry with custom GLB/GLTF models.
+ *
+ * @packageDocumentation
+ */
+interface Avl3DModelOverrides {
+    /** GLB URL for orbital nodes (replaces sphere) */
+    orbital?: string;
+    /** GLB URL for entity core (replaces icosahedron) */
+    entity?: string;
+    /** GLB URL for state nodes (replaces sphere) */
+    state?: string;
+    /** GLB URL for guard gates (replaces octahedron) */
+    guard?: string;
+    /** GLB URL for page portals (replaces plane) */
+    page?: string;
+}
+interface Avl3DConfig {
+    /** Custom 3D model URLs to replace default primitive geometry */
+    modelOverrides: Avl3DModelOverrides;
+    /** Whether postprocessing effects are enabled */
+    effectsEnabled: boolean;
+}
+declare const Avl3DContext: React$1.Context<Avl3DConfig>;
+/**
+ * Access the current AVL 3D configuration.
+ * Returns model overrides and effect settings.
+ */
+declare function useAvl3DConfig(): Avl3DConfig;
+
+/**
+ * Avl3DViewer - Interactive 3D Orbital Visualization
+ *
+ * The host organism that owns the R3F Canvas and delegates to 3D scene
+ * renderers at each zoom level. The 3D equivalent of AvlCosmicZoom.
+ *
+ * Reuses avl-schema-parser.ts and avl-zoom-state.ts directly.
+ *
+ * @packageDocumentation
+ */
+
+interface Avl3DViewerProps {
+    /** The orbital schema (parsed object or JSON string) */
+    schema: OrbitalSchema | string;
+    /** CSS class for the outer container */
+    className?: string;
+    /** Enable animations (default: true) */
+    animated?: boolean;
+    /** Pre-select an orbital on mount */
+    initialOrbital?: string;
+    /** Pre-select a trait on mount */
+    initialTrait?: string;
+    /** Callback when zoom level changes */
+    onZoomChange?: (level: ZoomLevel, context: {
+        orbital?: string;
+        trait?: string;
+    }) => void;
+    /** Container width */
+    width?: number | string;
+    /** Container height */
+    height?: number | string;
+    /** Enable postprocessing effects (bloom, DOF, vignette). Default: true */
+    effects?: boolean;
+    /** Custom 3D model URLs to replace default primitive geometry */
+    modelOverrides?: Avl3DModelOverrides;
+}
+declare const Avl3DViewer: React__default.FC<Avl3DViewerProps>;
+
+/**
+ * Avl3DApplicationScene - Galaxy view of all orbitals.
+ *
+ * Positions orbitals on a golden-ratio spiral and renders cross-orbital
+ * event wires between them. The 3D equivalent of AvlApplicationScene.
+ *
+ * @packageDocumentation
+ */
+
+interface Avl3DApplicationSceneProps {
+    /** Parsed application-level data */
+    data: ApplicationLevelData;
+    /** Click handler for an orbital */
+    onOrbitalClick?: (orbitalName: string) => void;
+    /** Primary color */
+    color?: string;
+}
+declare const Avl3DApplicationScene: React__default.FC<Avl3DApplicationSceneProps>;
+
+/**
+ * Avl3DOrbitalScene - Solar system view of a single orbital.
+ *
+ * Renders entity core at center, trait orbit rings, and page portals.
+ * The 3D equivalent of AvlOrbitalScene.
+ *
+ * @packageDocumentation
+ */
+
+interface Avl3DOrbitalSceneProps {
+    /** Parsed orbital-level data */
+    data: OrbitalLevelData;
+    /** Click handler for a trait */
+    onTraitClick?: (traitName: string) => void;
+    /** Currently highlighted trait */
+    highlightedTrait?: string | null;
+    /** Highlight change handler */
+    onTraitHighlight?: (traitName: string | null) => void;
+    /** Primary color */
+    color?: string;
+}
+declare const Avl3DOrbitalScene: React__default.FC<Avl3DOrbitalSceneProps>;
+
+/**
+ * Avl3DTraitScene - 3D state machine view for a single trait.
+ *
+ * Positions states on a fibonacci sphere and renders transition arcs
+ * between them. The 3D equivalent of AvlTraitScene.
+ *
+ * @packageDocumentation
+ */
+
+interface Avl3DTraitSceneProps {
+    /** Parsed trait-level data */
+    data: TraitLevelData;
+    /** Click handler for a transition */
+    onTransitionClick?: (transitionIndex: number) => void;
+    /** Primary color */
+    color?: string;
+}
+declare const Avl3DTraitScene: React__default.FC<Avl3DTraitSceneProps>;
+
+/**
+ * Avl3DTransitionScene - 3D expression tree and effect chain view.
+ *
+ * Renders a detailed view of a single transition with its guard
+ * expression tree and effect chain. The 3D equivalent of AvlTransitionScene.
+ *
+ * @packageDocumentation
+ */
+
+interface Avl3DTransitionSceneProps {
+    /** Parsed transition-level data */
+    data: TransitionLevelData;
+    /** Primary color */
+    color?: string;
+}
+declare const Avl3DTransitionScene: React__default.FC<Avl3DTransitionSceneProps>;
+
+/**
+ * Avl3DEffects - Postprocessing effects and ambient visuals for AVL 3D.
+ *
+ * Two layers:
+ * 1. Ambient visuals (sparkles, starfield) - always rendered via drei
+ * 2. Postprocessing (bloom, DOF, vignette) - rendered via @react-three/postprocessing
+ *
+ * @packageDocumentation
+ */
+
+interface Avl3DEffectsProps {
+    /** Current zoom level (effects vary by level) */
+    level: ZoomLevel;
+    /** Enable/disable all effects */
+    enabled?: boolean;
+}
+declare const Avl3DEffects: React__default.FC<Avl3DEffectsProps>;
+
+/**
+ * avl-3d-layout.ts
+ *
+ * Pure math utilities for 3D positioning of AVL visualization nodes.
+ * The 3D equivalent of avl-layout.ts (2D positioning helpers).
+ *
+ * @packageDocumentation
+ */
+
+interface Position3D {
+    x: number;
+    y: number;
+    z: number;
+}
+interface ExprTreeNode3D {
+    label: string;
+    type: 'operator' | 'literal' | 'binding';
+    children?: ExprTreeNode3D[];
+}
+interface TreeLayoutResult {
+    node: ExprTreeNode3D;
+    position: Position3D;
+}
+/**
+ * Refined palette following Almadar UI Beauty principles:
+ * - No pure black: deep navy tint (#0c1222) instead of #0A0A1A
+ * - 60-30-10 rule: 60% deep background, 30% muted blues/grays, 10% bright accents
+ * - Desaturated for dark backgrounds: softer blues, warmer golds
+ * - Depth through color layering: surfaces get progressively lighter
+ */
+declare const AVL_3D_COLORS: {
+    readonly orbitalSphere: "#161b2e";
+    readonly orbitalRim: "#5b9bd5";
+    readonly entityCore: "#f0c040";
+    readonly entityCoreGlow: "#ffd866";
+    readonly traitOrbit: "#5b9bd5";
+    readonly traitOrbitHighlight: "#7ab8f5";
+    readonly stateIdle: "#1e2a3a";
+    readonly stateEdge: "#5b9bd5";
+    readonly stateActive: "#4ecb71";
+    readonly transitionArc: "#e0944a";
+    readonly transitionArcHover: "#f0a860";
+    readonly guardPass: "#4ecb71";
+    readonly guardFail: "#f06060";
+    readonly crossWire: "#a78bda";
+    readonly crossWireGlow: "#c4a8f0";
+    readonly pagePortal: "#40c8aa";
+    readonly background: "#0c1222";
+    readonly backgroundSurface: "#111a2e";
+    readonly fog: "#0c1222";
+    readonly sparkle: "#7ab8f5";
+    readonly sparkleWarm: "#f0c040";
+};
+/**
+ * Positions N nodes on a golden-ratio spiral in the XZ plane (y=0).
+ * Used as initial positions for the force-directed layout.
+ */
+declare function goldenSpiralPositions(count: number, baseRadius: number): Position3D[];
+/**
+ * Distributes N points on a sphere surface using Fibonacci lattice.
+ * Produces near-uniform spacing regardless of count.
+ */
+declare function fibonacciSpherePositions(count: number, radius: number): Position3D[];
+/**
+ * Evenly spaces N points on a tilted ring (elliptical orbit).
+ * `tilt` is the ring's inclination in radians relative to the XZ plane.
+ */
+declare function orbitRingPositions(count: number, radius: number, tilt: number): Position3D[];
+/**
+ * Creates a QuadraticBezierCurve3 between two 3D points with a control
+ * point offset perpendicular to the from-to line. The offset direction
+ * is computed in 3D using a cross product with the up vector.
+ */
+declare function arcCurve3D(from: [number, number, number], to: [number, number, number], offset: number): QuadraticBezierCurve3;
+/**
+ * Creates a loop curve above a point for self-transitions.
+ */
+declare function selfLoopCurve3D(position: [number, number, number], loopRadius: number): QuadraticBezierCurve3;
+/**
+ * Recursively positions an expression tree in 3D space.
+ * Root at origin, children spread horizontally, depth goes downward (negative Y).
+ */
+declare function treeLayout3D(node: ExprTreeNode3D, origin: Position3D, horizontalSpacing: number, verticalSpacing?: number): TreeLayoutResult[];
+declare const CAMERA_POSITIONS: {
+    readonly application: {
+        readonly position: [number, number, number];
+        readonly target: [number, number, number];
+    };
+    readonly orbital: {
+        readonly position: [number, number, number];
+        readonly target: [number, number, number];
+    };
+    readonly trait: {
+        readonly position: [number, number, number];
+        readonly target: [number, number, number];
+    };
+    readonly transition: {
+        readonly position: [number, number, number];
+        readonly target: [number, number, number];
+    };
+};
+
+export { AVL_3D_COLORS, AssetLoader, type AssetLoadingState, Avl3DApplicationScene, type Avl3DApplicationSceneProps, type Avl3DConfig, Avl3DContext, Avl3DEffects, type Avl3DEffectsProps, type Avl3DModelOverrides, Avl3DOrbitalScene, type Avl3DOrbitalSceneProps, Avl3DTraitScene, type Avl3DTraitSceneProps, Avl3DTransitionScene, type Avl3DTransitionSceneProps, Avl3DViewer, type Avl3DViewerProps, CAMERA_POSITIONS, Camera3D, type Camera3DHandle, type Camera3DProps, type CameraMode$1 as CameraMode, Canvas3DErrorBoundary, type Canvas3DErrorBoundaryProps, type Canvas3DErrorBoundaryState, Canvas3DHost, type Canvas3DHostHandle, type Canvas3DHostProps, Canvas3DLoadingState, type Canvas3DLoadingStateProps, type CullingOptions, Canvas3DHost as GameCanvas3D, type GameCanvas3DEventConfig, type Grid3DConfig, type GridCoordinate, type GridHit, type LODConfig, type LODLevel, Lighting3D, type Lighting3DProps, type LoadedModel, ModelLoader, type ModelLoaderProps, type NodeType, type Position3D, type RaycastHit, Scene3D, type Scene3DProps, type SceneGraphNode, SpatialHashGrid, type UseAssetLoaderOptions, type UseAssetLoaderReturn, type UseGameCanvas3DEventsOptions, type UseGameCanvas3DEventsReturn, type UseRaycasterOptions, type UseRaycasterReturn, type UseSceneGraphReturn, type UseThreeOptions, type UseThreeReturn, arcCurve3D, assetLoader, calculateLODLevel, createGridHighlight, cullInstancedMesh, fibonacciSpherePositions, filterByFrustum, getCellsInRadius, getNeighbors, getVisibleIndices, goldenSpiralPositions, gridDistance, gridManhattanDistance, gridToWorld, isInBounds, isInFrustum, normalizeMouseCoordinates, orbitRingPositions, raycastToObjects, raycastToPlane, selfLoopCurve3D, treeLayout3D, updateInstanceLOD, useAssetLoader, useAvl3DConfig, useGameCanvas3DEvents, useRaycaster, useSceneGraph, useThree, worldToGrid };