@almadar/ui 2.20.0 → 2.20.6

package/dist/components/atoms/avl/Avl3DLabel.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Avl3DLabel - Billboard text label for 3D AVL visualizations.
+ *
+ * Uses drei's Html component to render text that always faces the camera.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface Avl3DLabelProps {
+    /** 3D position [x, y, z] */
+    position: [number, number, number];
+    /** Label text */
+    text: string;
+    /** Text color (CSS) */
+    color?: string;
+    /** Font size in px */
+    fontSize?: number;
+    /** CSS class */
+    className?: string;
+    /** Hide label when behind other objects */
+    occlude?: boolean;
+}
+export declare const Avl3DLabel: React.FC<Avl3DLabelProps>;

package/dist/components/atoms/avl/Avl3DTooltip.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Avl3DTooltip - Styled tooltip card for 3D AVL hover info.
+ *
+ * Uses drei's Html to render a DOM card in 3D space that always
+ * faces the camera. Shows contextual info based on the hovered node.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface Avl3DTooltipProps {
+    /** 3D position [x, y, z] */
+    position: [number, number, number];
+    /** Tooltip title (bold, top line) */
+    title: string;
+    /** Key-value rows to display */
+    rows: Array<{
+        label: string;
+        value: string;
+    }>;
+    /** Optional accent color for the left border */
+    accentColor?: string;
+    /** CSS class */
+    className?: string;
+}
+export declare const Avl3DTooltip: React.FC<Avl3DTooltipProps>;

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

@@ -18,3 +18,5 @@ export { AvlOperator, type AvlOperatorProps } from './AvlOperator';
 export { AvlSExpr, type AvlSExprProps } from './AvlSExpr';
 export { AvlLiteral, type AvlLiteralProps } from './AvlLiteral';
 export { AvlBindingRef, type AvlBindingRefProps } from './AvlBindingRef';
+export { Avl3DLabel, type Avl3DLabelProps } from './Avl3DLabel';
+export { Avl3DTooltip, type Avl3DTooltipProps } from './Avl3DTooltip';

package/dist/components/index.cjs

@@ -12257,7 +12257,8 @@ function MapView({
               marker.id
             ))
           ]
-        }
+        },
+        `map-${centerLat}-${centerLng}-${zoom}`
       )
     }
   );
@@ -12830,6 +12831,7 @@ var Lightbox = ({
       ),
       onClick: handleClose,
       role: "dialog",
+      "data-pattern": "lightbox",
       "aria-modal": "true",
       "aria-label": currentImage?.alt ?? "Image viewer",
       children: [

package/dist/components/index.js

@@ -12227,7 +12227,8 @@ function MapView({
               marker.id
             ))
           ]
-        }
+        },
+        `map-${centerLat}-${centerLng}-${zoom}`
       )
     }
   );
@@ -12800,6 +12801,7 @@ var Lightbox = ({
       ),
       onClick: handleClose,
       role: "dialog",
+      "data-pattern": "lightbox",
       "aria-modal": "true",
       "aria-label": currentImage?.alt ?? "Image viewer",
       children: [

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

@@ -0,0 +1,22 @@
+/**
+ * Avl3DCrossWire - Inter-orbital event connection tube.
+ *
+ * Renders a curved tube between two orbitals representing
+ * a cross-orbital emit/listen event connection.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface Avl3DCrossWireProps {
+    /** Start position [x, y, z] */
+    from: [number, number, number];
+    /** End position [x, y, z] */
+    to: [number, number, number];
+    /** Event name to display */
+    eventName: string;
+    /** Wire color override */
+    color?: string;
+    /** CSS class */
+    className?: string;
+}
+export declare const Avl3DCrossWire: React.FC<Avl3DCrossWireProps>;

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

@@ -0,0 +1,26 @@
+/**
+ * Avl3DEntityCore - Glowing entity center for the orbital solar system view.
+ *
+ * Renders an icosahedron with gold emissive glow, surrounded by
+ * field indicator particles and a point light.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface Avl3DEntityCoreProps {
+    /** Entity name */
+    name: string;
+    /** Number of fields */
+    fieldCount: number;
+    /** Persistence type */
+    persistence: string;
+    /** 3D position [x, y, z] */
+    position: [number, number, number];
+    /** Field type strings for V5 shape encoding (optional, falls back to spheres) */
+    fields?: string[];
+    /** Color override */
+    color?: string;
+    /** CSS class for label */
+    className?: string;
+}
+export declare const Avl3DEntityCore: React.FC<Avl3DEntityCoreProps>;

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

@@ -0,0 +1,21 @@
+/**
+ * Avl3DExprTree - 3D s-expression tree for guard/effect visualization.
+ *
+ * Renders operators as rounded boxes, literals as small spheres,
+ * bindings as wireframe spheres, connected by thin cylinders.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { ExprTreeNode } from '../../organisms/avl/avl-schema-parser';
+export interface Avl3DExprTreeProps {
+    /** The expression tree to render */
+    expression: ExprTreeNode;
+    /** Root position [x, y, z] */
+    position: [number, number, number];
+    /** Color override */
+    color?: string;
+    /** CSS class */
+    className?: string;
+}
+export declare const Avl3DExprTree: React.FC<Avl3DExprTreeProps>;

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

@@ -0,0 +1,29 @@
+/**
+ * Avl3DOrbitalNode - Orbital node for the galaxy view.
+ *
+ * Shape: TORUS (ring) with entity nucleus floating inside.
+ * The ring shape literally represents "orbital" and is visually
+ * distinct from all other AVL primitives.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface Avl3DOrbitalNodeProps {
+    /** Orbital name */
+    name: string;
+    /** Entity name */
+    entityName: string;
+    /** Number of traits (affects ring size and scale) */
+    traitCount: number;
+    /** Number of pages (affects glow brightness) */
+    pageCount?: number;
+    /** Entity persistence type */
+    persistence?: string;
+    /** 3D position [x, y, z] */
+    position: [number, number, number];
+    /** Click handler */
+    onClick?: () => void;
+    /** CSS class for label */
+    className?: string;
+}
+export declare const Avl3DOrbitalNode: React.FC<Avl3DOrbitalNodeProps>;

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

@@ -0,0 +1,34 @@
+/**
+ * Avl3DStateNode - State node in the 3D state machine view.
+ *
+ * Shape: ROUNDED BOX (matches the 2D rounded rectangle).
+ * Visually distinct from orbital torus, entity icosahedron, guard octahedron.
+ *
+ * V3 fix: initial = green arrow cone offset to left, terminal = red stop octahedron offset to right.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface Avl3DStateNodeProps {
+    /** State name */
+    name: string;
+    /** Whether this is the initial state */
+    isInitial?: boolean;
+    /** Whether this is a terminal state */
+    isTerminal?: boolean;
+    /** 3D position [x, y, z] */
+    position: [number, number, number];
+    /** Whether this state is currently active */
+    active?: boolean;
+    /** Click handler */
+    onClick?: () => void;
+    /** Number of incoming transitions */
+    incomingCount?: number;
+    /** Number of outgoing transitions */
+    outgoingCount?: number;
+    /** Color override */
+    color?: string;
+    /** CSS class for label */
+    className?: string;
+}
+export declare const Avl3DStateNode: React.FC<Avl3DStateNodeProps>;

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

@@ -0,0 +1,38 @@
+/**
+ * Avl3DTransitionArc - Curved tube between two state nodes.
+ *
+ * Renders a tube geometry along a Bezier curve with optional guard gate
+ * and arrowhead cone. The 3D equivalent of SVG transition arrows.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface Avl3DTransitionArcProps {
+    /** Start position [x, y, z] */
+    from: [number, number, number];
+    /** End position [x, y, z] */
+    to: [number, number, number];
+    /** Event name */
+    event: string;
+    /** Whether this transition has a guard */
+    hasGuard?: boolean;
+    /** Number of effects */
+    effectCount: number;
+    /** Effect type names for V4 micro-icons */
+    effectTypes?: string[];
+    /** Index (for fanning parallel transitions) */
+    index: number;
+    /** Whether this is a self-transition */
+    isSelf?: boolean;
+    /** Source state name (for tooltip) */
+    fromState?: string;
+    /** Target state name (for tooltip) */
+    toState?: string;
+    /** Click handler */
+    onClick?: () => void;
+    /** Color override */
+    color?: string;
+    /** CSS class */
+    className?: string;
+}
+export declare const Avl3DTransitionArc: React.FC<Avl3DTransitionArcProps>;

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

@@ -5,3 +5,9 @@ export { AvlEmitListen, type AvlEmitListenProps } from './AvlEmitListen';
 export { AvlSlotMap, type AvlSlotMapProps, type AvlSlotMapSlot } from './AvlSlotMap';
 export { AvlExprTree, type AvlExprTreeProps, type AvlExprTreeNode } from './AvlExprTree';
 export { ringPositions, arcPath, radialPositions, gridPositions, curveControlPoint } from './avl-layout';
+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/organisms/avl/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 './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/organisms/avl/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 './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/organisms/avl/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 './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/organisms/avl/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 './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/organisms/avl/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 './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/organisms/avl/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 './avl-zoom-state';
+import { type Avl3DModelOverrides } from './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/organisms/avl/AvlOrbitalScene.d.ts

@@ -9,9 +9,13 @@ import type { OrbitalLevelData } from './avl-schema-parser';
 export interface AvlOrbitalSceneProps {
     data: OrbitalLevelData;
     color?: string;
+    /** Currently highlighted trait (before zooming in) */
+    highlightedTrait?: string | null;
     onTraitClick?: (traitName: string, position: {
         x: number;
         y: number;
     }) => void;
+    /** Called when a trait tab is hovered/selected (highlight without zoom) */
+    onTraitHighlight?: (traitName: string | null) => void;
 }
 export declare const AvlOrbitalScene: React.FC<AvlOrbitalSceneProps>;

package/dist/components/organisms/avl/avl-3d-context.d.ts

@@ -0,0 +1,32 @@
+/**
+ * avl-3d-context.ts
+ *
+ * React context for AVL 3D model overrides and configuration.
+ * Allows replacing primitive geometry with custom GLB/GLTF models.
+ *
+ * @packageDocumentation
+ */
+export 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;
+}
+export interface Avl3DConfig {
+    /** Custom 3D model URLs to replace default primitive geometry */
+    modelOverrides: Avl3DModelOverrides;
+    /** Whether postprocessing effects are enabled */
+    effectsEnabled: boolean;
+}
+export declare const Avl3DContext: import("react").Context<Avl3DConfig>;
+/**
+ * Access the current AVL 3D configuration.
+ * Returns model overrides and effect settings.
+ */
+export declare function useAvl3DConfig(): Avl3DConfig;

package/dist/components/organisms/avl/avl-3d-layout.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 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
+ */
+import { QuadraticBezierCurve3 } from 'three';
+export interface Position3D {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface ExprTreeNode3D {
+    label: string;
+    type: 'operator' | 'literal' | 'binding';
+    children?: ExprTreeNode3D[];
+}
+export 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
+ */
+export 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.
+ */
+export declare function goldenSpiralPositions(count: number, baseRadius: number): Position3D[];
+interface ForceEdge {
+    from: number;
+    to: number;
+}
+/**
+ * Runs a simple force-directed simulation to cluster connected nodes.
+ * Connected nodes attract, all nodes repel. Runs for a fixed number of iterations.
+ *
+ * @param count Number of nodes
+ * @param edges Connections between nodes (indices)
+ * @param baseRadius Approximate spread radius
+ * @param iterations Simulation steps (default 80)
+ */
+export declare function forceDirectedPositions(count: number, edges: ForceEdge[], baseRadius: number, iterations?: number): Position3D[];
+/**
+ * Distributes N points on a sphere surface using Fibonacci lattice.
+ * Produces near-uniform spacing regardless of count.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function arcCurve3D(from: [number, number, number], to: [number, number, number], offset: number): QuadraticBezierCurve3;
+/**
+ * Creates a loop curve above a point for self-transitions.
+ */
+export 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).
+ */
+export declare function treeLayout3D(node: ExprTreeNode3D, origin: Position3D, horizontalSpacing: number, verticalSpacing?: number): TreeLayoutResult[];
+export 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 {};

package/dist/components/organisms/avl/avl-zoom-state.d.ts

@@ -47,6 +47,9 @@ export type ZoomAction = {
     type: 'ANIMATION_COMPLETE';
 } | {
     type: 'RESET';
+} | {
+    type: 'SWITCH_TRAIT';
+    trait: string;
 };
 export declare const initialZoomState: ZoomState;
 export declare function zoomReducer(state: ZoomState, action: ZoomAction): ZoomState;