@almadar/ui 5.79.1 → 5.80.0

package/dist/components/avl/molecules/AvlClosedCircuit.d.ts

@@ -0,0 +1,20 @@
+import React from 'react';
+import type { AvlEffectType } from '../types/avl-atom-types';
+export interface AvlClosedCircuitState {
+    name: string;
+}
+export interface AvlClosedCircuitTransition {
+    from: string;
+    to: string;
+    event?: string;
+    guard?: string;
+    effects?: AvlEffectType[];
+}
+export interface AvlClosedCircuitProps {
+    states: AvlClosedCircuitState[];
+    transitions: AvlClosedCircuitTransition[];
+    className?: string;
+    color?: string;
+    animated?: boolean;
+}
+export declare const AvlClosedCircuit: React.FC<AvlClosedCircuitProps>;

package/dist/components/avl/molecules/AvlEmitListen.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+export interface AvlEmitListenProps {
+    emitter: {
+        name: string;
+        fields?: number;
+    };
+    listener: {
+        name: string;
+        fields?: number;
+    };
+    eventName?: string;
+    className?: string;
+    color?: string;
+    animated?: boolean;
+}
+export declare const AvlEmitListen: React.FC<AvlEmitListenProps>;

package/dist/components/avl/molecules/AvlEventWireEdge.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AvlEventWireEdge — React Flow edge for emit/listen event wiring.
+ *
+ * Dashed orange Bezier path with event name label at midpoint.
+ * Uses AVL CONNECTION_COLORS.emitListen styling.
+ */
+import React from 'react';
+import { type Edge, type EdgeProps } from '@xyflow/react';
+export interface AvlEventWireEdgeData {
+    [key: string]: string | boolean | undefined;
+    event: string;
+    compatible?: boolean;
+}
+export type AvlEventWireFlowEdge = Edge<AvlEventWireEdgeData, 'eventWire'>;
+export declare const AvlEventWireEdge: React.FC<EdgeProps<AvlEventWireFlowEdge>>;

package/dist/components/avl/molecules/AvlExprTree.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+export interface AvlExprTreeNode {
+    label: string;
+    type: 'operator' | 'literal' | 'binding';
+    children?: AvlExprTreeNode[];
+}
+export interface AvlExprTreeProps {
+    expression: AvlExprTreeNode;
+    className?: string;
+    color?: string;
+    animated?: boolean;
+}
+export declare const AvlExprTree: React.FC<AvlExprTreeProps>;

package/dist/components/avl/molecules/AvlOrbitalNode.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AvlOrbitalNode — Single React Flow node type for the unified AVL canvas.
+ *
+ * Reads the current ZoomBand from context and renders the appropriate
+ * sub-component: SystemNode, ModuleCard, BehaviorView, or DetailView.
+ *
+ * Using a single node type (instead of switching types per zoom band)
+ * prevents React from unmounting/remounting nodes on zoom changes.
+ */
+import React from 'react';
+import type { NodeProps } from '@xyflow/react';
+export declare const AvlOrbitalNode: React.FC<NodeProps>;

package/dist/components/avl/molecules/AvlOrbitalUnit.d.ts

@@ -0,0 +1,20 @@
+import React from 'react';
+import type { AvlPersistenceKind } from '../types/avl-atom-types';
+export interface AvlOrbitalUnitTrait {
+    name: string;
+    color?: string;
+}
+export interface AvlOrbitalUnitPage {
+    name: string;
+}
+export interface AvlOrbitalUnitProps {
+    entityName: string;
+    fields?: number;
+    persistence?: AvlPersistenceKind;
+    traits: AvlOrbitalUnitTrait[];
+    pages: AvlOrbitalUnitPage[];
+    className?: string;
+    color?: string;
+    animated?: boolean;
+}
+export declare const AvlOrbitalUnit: React.FC<AvlOrbitalUnitProps>;

package/dist/components/avl/molecules/AvlPageEdge.d.ts

@@ -0,0 +1,8 @@
+/**
+ * AvlPageEdge — Thin solid page-reference edge.
+ *
+ * Slate colored, 1px, used for page-to-trait references.
+ */
+import React from 'react';
+import { type EdgeProps } from '@xyflow/react';
+export declare const AvlPageEdge: React.FC<EdgeProps>;

package/dist/components/avl/molecules/AvlSlotMap.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+export interface AvlSlotMapSlot {
+    name: string;
+    /** Manual position overrides. Omit for auto-layout. */
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
+export interface AvlSlotMapProps {
+    slots: AvlSlotMapSlot[];
+    pageWidth?: number;
+    pageHeight?: number;
+    className?: string;
+    color?: string;
+    animated?: boolean;
+}
+export declare const AvlSlotMap: React.FC<AvlSlotMapProps>;

package/dist/components/avl/molecules/AvlStateMachine.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import type { AvlEffectType } from '../types/avl-atom-types';
+export interface AvlStateMachineState {
+    name: string;
+    isInitial?: boolean;
+    isTerminal?: boolean;
+}
+export interface AvlStateMachineTransition {
+    from: string;
+    to: string;
+    event?: string;
+    guard?: string;
+    effects?: AvlEffectType[];
+}
+export interface AvlStateMachineProps {
+    states: AvlStateMachineState[];
+    transitions: AvlStateMachineTransition[];
+    className?: string;
+    color?: string;
+    animated?: boolean;
+}
+export declare const AvlStateMachine: React.FC<AvlStateMachineProps>;

package/dist/components/avl/molecules/AvlSwimLane.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+export interface AvlSwimLaneProps {
+    listenedEvents: string[];
+    emittedEvents: string[];
+    centerWidth: number;
+    height: number;
+    color?: string;
+    children: React.ReactNode;
+}
+export declare const AvlSwimLane: React.FC<AvlSwimLaneProps>;

package/dist/components/avl/molecules/AvlTransitionEdge.d.ts

@@ -0,0 +1,17 @@
+/**
+ * AvlTransitionEdge — React Flow edge for state machine transitions.
+ *
+ * Bezier path with event label at midpoint. Guard diamond and effect
+ * dot indicators shown inline. Forward transitions are solid dark,
+ * backward transitions are dashed lighter.
+ */
+import React from 'react';
+import { type Edge, type EdgeProps } from '@xyflow/react';
+export interface AvlTransitionEdgeData {
+    [key: string]: string | boolean | undefined;
+    event: string;
+    hasGuard?: boolean;
+    hasEffects?: boolean;
+}
+export type AvlTransitionFlowEdge = Edge<AvlTransitionEdgeData, 'transition'>;
+export declare const AvlTransitionEdge: React.FC<EdgeProps<AvlTransitionFlowEdge>>;

package/dist/components/avl/molecules/AvlTransitionLane.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import { type AvlEffectType } from '../types/avl-atom-types';
+export interface AvlTransitionLaneEffect {
+    type: AvlEffectType | string;
+}
+export interface AvlTransitionLaneProps {
+    event: string;
+    guard?: string;
+    effects: AvlTransitionLaneEffect[];
+    width: number;
+    x?: number;
+    y?: number;
+    isBackward?: boolean;
+    isSelfLoop?: boolean;
+    color?: string;
+    onTransitionClick?: () => void;
+}
+export declare const AvlTransitionLane: React.FC<AvlTransitionLaneProps>;

package/dist/components/avl/molecules/BehaviorComposeNode.d.ts

@@ -0,0 +1,13 @@
+/**
+ * BehaviorComposeNode
+ *
+ * React Flow custom node for behavior-level composition.
+ * Shows AvlBehaviorGlyph instead of live UI (OrbPreview).
+ * Each behavior is one compact node with event handles for wiring.
+ *
+ * This is the compose-level node. Double-clicking drills into
+ * the orbital-level view (OrbPreviewNode).
+ */
+import React from 'react';
+import { type NodeProps } from '@xyflow/react';
+export declare const BehaviorComposeNode: React.NamedExoticComponent<NodeProps>;

package/dist/components/avl/molecules/BehaviorView.d.ts

@@ -0,0 +1,12 @@
+/**
+ * BehaviorView — Full state machine for the behavior zoom band (1.0x-2.5x).
+ *
+ * Uses ELK layout from avl-elk-layout.ts. Renders AvlState, AvlTransitionLane,
+ * and AvlSwimLane inside an inline SVG within a React Flow node.
+ */
+import React from 'react';
+import type { AvlNodeData } from '../types/avl-canvas-types';
+export interface BehaviorViewProps {
+    data: AvlNodeData;
+}
+export declare const BehaviorView: React.FC<BehaviorViewProps>;

package/dist/components/avl/molecules/DetailView.d.ts

@@ -0,0 +1,13 @@
+/**
+ * DetailView — Transition specification card for the detail zoom band (2.5x-5.0x).
+ *
+ * Renders a spec card with: from/to AvlState nodes, AvlEvent trigger,
+ * AvlGuard diamond, numbered AvlEffect icons with binding paths,
+ * and AvlFieldType shapes.
+ */
+import React from 'react';
+import type { AvlNodeData } from '../types/avl-canvas-types';
+export interface DetailViewProps {
+    data: AvlNodeData;
+}
+export declare const DetailView: React.FC<DetailViewProps>;

package/dist/components/avl/molecules/EventFlowEdge.d.ts

@@ -0,0 +1,13 @@
+/**
+ * EventFlowEdge
+ *
+ * React Flow edge for the V3 FlowCanvas. Shows the event name and
+ * optionally the trigger element (button label) that fires it.
+ *
+ * When the edge originates from a specific event source handle,
+ * the label shows "Button Label \u2192 EVENT" to make the connection
+ * between UI element and transition clear.
+ */
+import React from 'react';
+import { type EdgeProps } from '@xyflow/react';
+export declare const EventFlowEdge: React.NamedExoticComponent<EdgeProps>;

package/dist/components/avl/molecules/MiniStateMachine.d.ts

@@ -0,0 +1,14 @@
+/**
+ * MiniStateMachine — Inline simplified state machine for the ModuleCard.
+ *
+ * Renders a compact left-to-right flow of AvlState nodes connected
+ * by AvlTransition arrows, with AvlEffect icons below.
+ * No ELK layout needed — uses simple horizontal positioning.
+ */
+import React from 'react';
+import type { TraitLevelData } from '../lib/avl-schema-parser';
+export interface MiniStateMachineProps {
+    data: TraitLevelData;
+    className?: string;
+}
+export declare const MiniStateMachine: React.FC<MiniStateMachineProps>;

package/dist/components/avl/molecules/ModuleCard.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ModuleCard — Structured card for the module zoom band (0.4x-1.0x).
+ *
+ * Renders AVL primitives inside a card container:
+ * - Entity section: AvlEntity glyph + AvlPersistence + AvlFieldType grid
+ * - Trait sections: MiniStateMachine per trait + AvlEffect icons + emit/listen indicators
+ * - Pages section: AvlPage squares with route labels
+ */
+import React from 'react';
+import type { AvlNodeData } from '../types/avl-canvas-types';
+export interface ModuleCardProps {
+    data: AvlNodeData;
+}
+/**
+ * Self-contained ModuleCard. The connection `<Handle>`s need the ReactFlow store,
+ * so standalone they'd throw ("no zustand provider as an ancestor"). When this
+ * card isn't already a flow node (`useNodeId() === null`) it bundles its own
+ * `<ReactFlowProvider>` so it renders anywhere; inside `<FlowCanvas>` it's a real
+ * node and renders raw (no nested provider). The provider is an implementation
+ * detail, never a precondition for using the component.
+ */
+export declare const ModuleCard: React.FC<ModuleCardProps>;

package/dist/components/avl/molecules/OrbPreviewNode.d.ts

@@ -0,0 +1,38 @@
+/**
+ * OrbPreviewNode
+ *
+ * React Flow node that renders a real OrbPreview inside it.
+ * The canvas is always live and editable (like Figma). Clicking any
+ * rendered UI element selects its pattern and shows props in the
+ * TransitionPanel. No edit mode toggle needed.
+ *
+ * The header is the drag handle for React Flow. The content area
+ * passes clicks through to the pattern elements.
+ */
+import React from 'react';
+import { type NodeProps } from '@xyflow/react';
+import type { PreviewNodeData, ScreenSize } from '../types/avl-preview-types';
+export declare const ScreenSizeContext: React.Context<ScreenSize>;
+/** Selected pattern info, emitted when user clicks a UI element in the node. */
+export interface SelectedPattern {
+    /** The pattern type (e.g., "button", "input", "stack"). */
+    patternType: string;
+    /** The DOM element's data-pattern-id if available. */
+    patternId?: string;
+    /** The node this pattern belongs to. */
+    nodeData: PreviewNodeData;
+    /** The source trait for this slot content. */
+    sourceTrait?: string;
+    /** Bounding rect relative to the node for floating inspector positioning. */
+    rect?: {
+        top: number;
+        left: number;
+        width: number;
+        height: number;
+    };
+}
+export declare const PatternSelectionContext: React.Context<{
+    selected: SelectedPattern | null;
+    select: (pattern: SelectedPattern | null) => void;
+}>;
+export declare const OrbPreviewNode: React.NamedExoticComponent<NodeProps>;

package/dist/components/avl/molecules/SystemNode.d.ts

@@ -0,0 +1,12 @@
+/**
+ * SystemNode — Compact orbital node for the system zoom band (0.1x-0.4x).
+ *
+ * Renders miniature AVL primitives: entity glyph, field-type dots,
+ * state chain (role-colored dots), and page squares.
+ */
+import React from 'react';
+import type { AvlNodeData } from '../types/avl-canvas-types';
+export interface SystemNodeProps {
+    data: AvlNodeData;
+}
+export declare const SystemNode: React.FC<SystemNodeProps>;

package/dist/components/avl/molecules/TraitCardNode.d.ts

@@ -0,0 +1,33 @@
+/**
+ * TraitCardNode — React Flow node for the `trait-expanded` view level.
+ *
+ * Renders one card per trait of a single orbital. The card body shows
+ * the trait's state-machine flow chart (states + transitions, laid out
+ * by ELK) via the existing `AvlTraitScene` organism. Clicking a
+ * transition arc drills into L4 transition detail.
+ *
+ * Left edge has one target handle per `listens[]` event; right edge
+ * has one source handle per `emits[]` event. Edges produced by
+ * `orbitalToTraitGraph` connect emit handles to listen handles where
+ * the event names match within the same orbital.
+ *
+ * Transition clicks bubble through `TraitCardSelectionContext`
+ * (mirrors `PatternSelectionContext` in `OrbPreviewNode`). FlowCanvas
+ * wraps the canvas in a provider that translates the context callback
+ * into its `onNodeClick({ level: 'transition', ... })` prop.
+ */
+import React from 'react';
+import { type NodeProps } from '@xyflow/react';
+export interface TraitCardTransitionClick {
+    orbitalName: string;
+    traitName: string;
+    transitionEvent: string;
+    fromState: string;
+    toState: string;
+    index: number;
+}
+export interface TraitCardSelectionContextValue {
+    selectTransition: (sel: TraitCardTransitionClick) => void;
+}
+export declare const TraitCardSelectionContext: React.Context<TraitCardSelectionContextValue>;
+export declare const TraitCardNode: React.NamedExoticComponent<NodeProps>;

package/dist/components/avl/molecules/index.d.ts

@@ -0,0 +1,38 @@
+export { AvlStateMachine, type AvlStateMachineProps, type AvlStateMachineState, type AvlStateMachineTransition } from './AvlStateMachine';
+export { AvlOrbitalUnit, type AvlOrbitalUnitProps, type AvlOrbitalUnitTrait, type AvlOrbitalUnitPage } from './AvlOrbitalUnit';
+export { AvlClosedCircuit, type AvlClosedCircuitProps, type AvlClosedCircuitState, type AvlClosedCircuitTransition } from './AvlClosedCircuit';
+export { AvlEmitListen, type AvlEmitListenProps } from './AvlEmitListen';
+export { AvlSlotMap, type AvlSlotMapProps, type AvlSlotMapSlot } from './AvlSlotMap';
+export { AvlExprTree, type AvlExprTreeProps, type AvlExprTreeNode } from './AvlExprTree';
+export { AvlTransitionLane, type AvlTransitionLaneProps, type AvlTransitionLaneEffect } from './AvlTransitionLane';
+export { AvlSwimLane, type AvlSwimLaneProps } from './AvlSwimLane';
+export { AvlBehaviorGlyph, type AvlBehaviorGlyphProps, type BehaviorLevel, type GlyphSize, type BehaviorGlyphChild, type BehaviorGlyphConnection, DOMAIN_COLORS } from './AvlBehaviorGlyph';
+export { ringPositions, arcPath, radialPositions, gridPositions, curveControlPoint } from '../lib/avl-layout';
+export { type ZoomBand, type AvlNodeData, type AvlEdgeData, type AvlEdgeKind, ZOOM_BAND_THRESHOLDS } from '../types/avl-canvas-types';
+export { computeZoomBand, zoomProgress, useZoomBand, ZoomBandContext } from '../lib/avl-zoom-band';
+export { schemaToFlowGraph } from '../lib/avl-flow-converter';
+export { computeTraitLayout, edgePath, stateWidth, STATE_H, type LayoutNode, type LayoutEdge, type ElkLayout } from '../lib/avl-elk-layout';
+export { SystemNode, type SystemNodeProps } from './SystemNode';
+export { MiniStateMachine, type MiniStateMachineProps } from './MiniStateMachine';
+export { ModuleCard, type ModuleCardProps } from './ModuleCard';
+export { BehaviorView, type BehaviorViewProps } from './BehaviorView';
+export { DetailView, type DetailViewProps } from './DetailView';
+export { AvlOrbitalNode } from './AvlOrbitalNode';
+export { AvlTransitionEdge, type AvlTransitionEdgeData, type AvlTransitionFlowEdge } from './AvlTransitionEdge';
+export { AvlEventWireEdge, type AvlEventWireEdgeData, type AvlEventWireFlowEdge } from './AvlEventWireEdge';
+export { AvlBackwardEdge } from './AvlBackwardEdge';
+export { AvlPageEdge } from './AvlPageEdge';
+export { AvlBindingEdge } from './AvlBindingEdge';
+export { type ViewLevel, type PreviewNodeData, type EventEdgeData, type PatternEventSource, type RenderUIEntry, type ScreenSize, SCREEN_SIZE_PRESETS } from '../types/avl-preview-types';
+export { schemaToOverviewGraph, orbitalToExpandedGraph } from '../lib/avl-preview-converter';
+export { OrbPreviewNode, ScreenSizeContext } from './OrbPreviewNode';
+export { EventFlowEdge } from './EventFlowEdge';
+export { type ComposeViewLevel, type BehaviorComposeNodeData, type BehaviorWireEdgeData, type BehaviorCanvasEntry, type ConnectableEvent } from '../types/avl-behavior-compose-types';
+export { BehaviorComposeNode } from './BehaviorComposeNode';
+export { behaviorsToComposeGraph, registryEntryToCanvasEntry, type BehaviorRegistryRecord } from '../lib/avl-behavior-compose-converter';
+export { Avl3DOrbitalNode, type Avl3DOrbitalNodeProps } from './Avl3DOrbitalNode';
+export { Avl3DCrossWire, type Avl3DCrossWireProps } from './Avl3DCrossWire';
+export { Avl3DEntityCore, type Avl3DEntityCoreProps } from './Avl3DEntityCore';
+export { Avl3DStateNode, type Avl3DStateNodeProps } from './Avl3DStateNode';
+export { Avl3DTransitionArc, type Avl3DTransitionArcProps } from './Avl3DTransitionArc';
+export { Avl3DExprTree, type Avl3DExprTreeProps } from './Avl3DExprTree';

package/dist/components/avl/organisms/Avl3DApplicationScene.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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
+ */
+import React from 'react';
+import type { ApplicationLevelData } from '../lib/avl-schema-parser';
+export interface Avl3DApplicationSceneProps {
+    /** Parsed application-level data */
+    data: ApplicationLevelData;
+    /** Click handler for an orbital */
+    onOrbitalClick?: (orbitalName: string) => void;
+    /** Primary color */
+    color?: string;
+}
+export declare const Avl3DApplicationScene: React.FC<Avl3DApplicationSceneProps>;

package/dist/components/avl/organisms/Avl3DEffects.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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
+ */
+import React from 'react';
+import type { ZoomLevel } from '../lib/avl-zoom-state';
+export interface Avl3DEffectsProps {
+    /** Current zoom level (effects vary by level) */
+    level: ZoomLevel;
+    /** Enable/disable all effects */
+    enabled?: boolean;
+}
+export declare const Avl3DEffects: React.FC<Avl3DEffectsProps>;

package/dist/components/avl/organisms/Avl3DOrbitalScene.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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
+ */
+import React from 'react';
+import type { OrbitalLevelData } from '../lib/avl-schema-parser';
+export 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;
+}
+export declare const Avl3DOrbitalScene: React.FC<Avl3DOrbitalSceneProps>;

package/dist/components/avl/organisms/Avl3DTraitScene.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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
+ */
+import React from 'react';
+import type { TraitLevelData } from '../lib/avl-schema-parser';
+export interface Avl3DTraitSceneProps {
+    /** Parsed trait-level data */
+    data: TraitLevelData;
+    /** Click handler for a transition */
+    onTransitionClick?: (transitionIndex: number) => void;
+    /** Primary color */
+    color?: string;
+}
+export declare const Avl3DTraitScene: React.FC<Avl3DTraitSceneProps>;

package/dist/components/avl/organisms/Avl3DTransitionScene.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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
+ */
+import React from 'react';
+import type { TransitionLevelData } from '../lib/avl-schema-parser';
+export interface Avl3DTransitionSceneProps {
+    /** Parsed transition-level data */
+    data: TransitionLevelData;
+    /** Primary color */
+    color?: string;
+}
+export declare const Avl3DTransitionScene: React.FC<Avl3DTransitionSceneProps>;

package/dist/components/avl/organisms/Avl3DViewer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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
+ */
+import React from 'react';
+import type { OrbitalSchema } from '@almadar/core';
+import { type ZoomLevel } from '../lib/avl-zoom-state';
+import { type Avl3DModelOverrides } from '../providers/avl-3d-context';
+export 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;
+}
+export declare const Avl3DViewer: React.FC<Avl3DViewerProps>;

package/dist/components/avl/organisms/AvlClickTarget.d.ts

@@ -0,0 +1,31 @@
+/**
+ * AvlClickTarget
+ *
+ * Transparent SVG rect overlay that makes AVL atoms clickable.
+ * AVL atoms render <g> elements which don't natively support
+ * bounding-box click events. This wrapper adds an invisible
+ * rect with pointer events and optional hover glow.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface AvlClickTargetProps {
+    /** Bounding box position */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Click handler */
+    onClick: () => void;
+    /** Hover callback */
+    onHover?: (hovering: boolean) => void;
+    /** Cursor style (default: pointer) */
+    cursor?: string;
+    /** Glow color on hover */
+    glowColor?: string;
+    /** Accessible label */
+    label?: string;
+    /** Children (the AVL atoms to render on top) */
+    children: React.ReactNode;
+}
+export declare const AvlClickTarget: React.FC<AvlClickTargetProps>;

package/dist/components/avl/organisms/AvlCosmicZoom.d.ts

@@ -0,0 +1,41 @@
+/**
+ * AvlCosmicZoom — Interactive Orbital Visualization
+ *
+ * V3: Delegates to FlowCanvas. Nodes are live OrbPreview renders
+ * of each orbital/transition. Two-level navigation (overview + expanded).
+ * Props interface preserved for backward compatibility with callers.
+ */
+import React from 'react';
+import type { OrbitalSchema } from '@almadar/core';
+import type { ZoomLevel } from '../lib/avl-zoom-state';
+export interface AvlCosmicZoomProps {
+    /** The orbital schema (parsed object or JSON string) */
+    schema: OrbitalSchema | string;
+    /** CSS class for the outer container */
+    className?: string;
+    /** Primary color for the visualization */
+    color?: 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;
+    /** Coverage data for verification overlay */
+    stateCoverage?: Record<string, 'covered' | 'uncovered' | 'partial'>;
+    /** Dynamic focus target. Changes animate the zoom to the specified orbital/trait. */
+    focusTarget?: {
+        type: 'orbital' | 'trait';
+        name: string;
+    };
+}
+export declare const AvlCosmicZoom: React.FC<AvlCosmicZoomProps>;