@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.30

package/dist/components/data-display/Timeline/TimelineItem.js

@@ -1,9 +1,11 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
-import React__default, { createContext, useRef, useState, useEffect, useContext } from 'react';
+import React__default, { createContext, useRef, useState, useEffect, useMemo, useContext } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
-import { useTimelineContext } from './Timeline.js';
-import { timelineHorizontalItemVariants, getDirectionalVariants, timelineItemVariants } from './Timeline.animations.js';
+import { useTimelineContext } from './TimelineContext.js';
+import { timelineHorizontalItemVariants, timelineItemVariants } from './Timeline.animations.js';
+import { stripMotionConflicts } from './Timeline.utils.js';
 
 // Create context for TimelineItem
 const TimelineItemContext = createContext(undefined);
@@ -14,26 +16,22 @@ const useTimelineItemContext = () => {
         throw new Error("Timeline.Marker and Timeline.Content must be used within Timeline.Item");
     return ctx;
 };
-const TimelineItem = React__default.forwardRef(({ children, className, status = "pending", ...props }, ref) => {
-    const { layout, align, theme, totalItems } = useTimelineContext();
+const TimelineItem = React__default.forwardRef(({ children, className, status = "pending", _index = 0, ...props }, ref) => {
+    const { layout, theme, totalItems } = useTimelineContext();
     const shouldReduceMotion = useReducedMotion();
     const itemRef = useRef(null);
     const [isVisible, setIsVisible] = useState(false);
-    // Determine item index from parent
+    // Index/first/last come from the root (single source of truth), not the DOM.
+    const index = _index;
+    const isFirst = index === 0;
+    const isLast = index === totalItems - 1;
+    const isHorizontal = layout === "horizontal";
     const resolvedRef = ref || itemRef;
-    // Find index among siblings for alternate layout
-    const [index, setIndex] = useState(0);
-    useEffect(() => {
-        const element = resolvedRef && "current" in resolvedRef ? resolvedRef.current : itemRef.current;
-        if (element === null || element === void 0 ? void 0 : element.parentElement) {
-            const siblings = Array.from(element.parentElement.children);
-            const idx = siblings.indexOf(element);
-            setIndex(idx);
-        }
-    }, [resolvedRef]);
-    // IntersectionObserver for scroll-triggered animation
+    // IntersectionObserver for scroll-triggered entry animation
     useEffect(() => {
-        const element = resolvedRef && "current" in resolvedRef ? resolvedRef.current : itemRef.current;
+        const element = resolvedRef && "current" in resolvedRef
+            ? resolvedRef.current
+            : itemRef.current;
         if (!element)
             return;
         const observer = new IntersectionObserver(([entry]) => {
@@ -45,41 +43,24 @@ const TimelineItem = React__default.forwardRef(({ children, className, status =
         observer.observe(element);
         return () => observer.disconnect();
     }, [resolvedRef]);
-    const isFirst = index === 0;
-    const isLast = index === totalItems - 1;
-    const isHorizontal = layout === "horizontal";
-    // Determine which side this item is on for alternate layout
-    const itemSide = align === "alternate"
-        ? index % 2 === 0
-            ? "left"
-            : "right"
-        : align;
-    // Select animation variants based on layout and alignment
+    // Select animation variants based on layout
     const getVariants = () => {
         if (shouldReduceMotion)
             return undefined;
         if (isHorizontal)
             return timelineHorizontalItemVariants;
-        if (align === "alternate") {
-            return getDirectionalVariants(itemSide);
-        }
         return timelineItemVariants;
     };
     // Context value for Marker and Content
-    const contextValue = {
+    const contextValue = useMemo(() => ({
         status,
         index,
         isFirst,
         isLast,
-    };
-    // Build className based on layout
-    const isAlternateRight = align === "alternate" && index % 2 !== 0;
-    // Filter out conflicting motion props from rest
-    const { onDrag, onDragEnd, onDragStart, onAnimationStart, onAnimationEnd, ...safeProps } = props;
+    }), [status, index, isFirst, isLast]);
+    const safeProps = stripMotionConflicts(props);
     const variants = getVariants();
-    return (jsx(TimelineItemContext.Provider, { value: contextValue, children: jsx(motion.div, { ref: ref || itemRef, className: cn(isHorizontal ? theme.itemStyleHorizontal : theme.itemStyle, 
-            // For right-aligned or alternate-right, reverse the flex direction
-            !isHorizontal && align === "right" && "flex-row-reverse", !isHorizontal && isAlternateRight && "flex-row-reverse", className), "data-status": status, "data-side": itemSide, "data-layout": layout, role: "listitem", initial: variants ? "hidden" : undefined, animate: variants && isVisible ? "visible" : variants ? "hidden" : undefined, variants: variants, ...safeProps, children: children }) }));
+    return (jsx(TimelineItemContext.Provider, { value: contextValue, children: jsx(motion.div, { ref: ref || itemRef, className: cn(isHorizontal ? theme.itemStyleHorizontal : theme.itemStyle, className), "data-status": status, "data-layout": layout, role: "listitem", "aria-current": status === "active" ? "step" : undefined, initial: variants ? "hidden" : undefined, animate: variants && isVisible ? "visible" : variants ? "hidden" : undefined, variants: variants, ...safeProps, children: children }) }));
 });
 TimelineItem.displayName = "TimelineItem";
 

package/dist/components/data-display/Timeline/TimelineMarker.js

@@ -1,12 +1,20 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { useReducedMotion, motion } from 'motion/react';
 import { CheckIcon } from '@heroicons/react/24/solid';
 import { cn } from '../../../utils/cn.js';
-import { useTimelineContext } from './Timeline.js';
+import { useTimelineContext } from './TimelineContext.js';
 import { useTimelineItemContext } from './TimelineItem.js';
 import { timelineMarkerVariants } from './Timeline.animations.js';
+import { stripMotionConflicts } from './Timeline.utils.js';
 
+// Screen-reader status text so status isn't conveyed by color/icon alone.
+const STATUS_LABEL = {
+    completed: "Completed",
+    active: "In progress",
+    pending: "Pending",
+};
 const TimelineMarker = React__default.forwardRef(({ icon, className, ...props }, ref) => {
     const { theme, layout } = useTimelineContext();
     const { status, isLast } = useTimelineItemContext();
@@ -19,20 +27,15 @@ const TimelineMarker = React__default.forwardRef(({ icon, className, ...props },
             return jsx(CheckIcon, { className: "w-4 h-4" });
         }
         if (status === "active") {
-            return jsx("span", { className: "w-2 h-2 rounded-full bg-white" });
+            return (jsx("span", { className: "w-2 h-2 rounded-full bg-[var(--color-primary)]" }));
         }
         // Pending: small neutral dot
         return (jsx("span", { className: "w-2 h-2 rounded-full bg-[var(--color-text-muted)]" }));
     };
     const isHorizontal = layout === "horizontal";
     const variants = shouldReduceMotion ? undefined : timelineMarkerVariants;
-    // Filter out conflicting motion props
-    const { onDrag, onDragEnd, onDragStart, onAnimationStart, onAnimationEnd, ...safeProps } = props;
-    return (jsxs("div", { className: cn("relative flex flex-col items-center", isHorizontal && "flex-row"), children: [jsx(motion.div, { ref: ref, className: cn(theme.markerStyle, theme.markerStatuses[status], className), "data-status": status, "aria-label": `${status} step`, initial: variants ? "hidden" : undefined, animate: variants ? "visible" : undefined, variants: variants, ...safeProps, children: renderIcon() }), !isLast && !isHorizontal && (jsx("div", { className: cn("w-0.5 flex-1 min-h-4", status === "completed"
-                    ? "bg-[var(--color-success)]"
-                    : "bg-[var(--color-border)]"), "aria-hidden": "true" })), !isLast && isHorizontal && (jsx("div", { className: cn("h-0.5 flex-1 min-w-4", status === "completed"
-                    ? "bg-[var(--color-success)]"
-                    : "bg-[var(--color-border)]"), "aria-hidden": "true" }))] }));
+    const safeProps = stripMotionConflicts(props);
+    return (jsxs("div", { className: cn("relative flex flex-col items-center", isHorizontal && "w-full"), children: [jsxs(motion.div, { ref: ref, className: cn(theme.markerStyle, theme.markerStatuses[status], className), "data-status": status, initial: variants ? "hidden" : undefined, animate: variants ? "visible" : undefined, variants: variants, ...safeProps, children: [jsx("span", { className: "sr-only", children: STATUS_LABEL[status] }), jsx("span", { "aria-hidden": "true", className: "flex items-center justify-center", children: renderIcon() })] }), !isLast && !isHorizontal && (jsx("div", { className: cn(theme.connectorStyle, status === "completed" && theme.connectorCompletedStyle), "aria-hidden": "true" })), !isLast && isHorizontal && (jsx("div", { className: cn(theme.connectorStyleHorizontal, status === "completed" && theme.connectorCompletedStyle), "aria-hidden": "true" }))] }));
 });
 TimelineMarker.displayName = "TimelineMarker";
 

package/dist/components/data-display/Timeline/index.d.ts

@@ -1,4 +1,4 @@
 import { Timeline } from "./Timeline";
-import { TimelineProps, TimelineItemProps, TimelineMarkerProps, TimelineContentProps, TimelineContextValue, TimelineItemContextValue, TimelineThemeOverrides, TimelineLayout, TimelineAlign, TimelineItemStatus } from "./Timeline.types";
+import { TimelineProps, TimelineItemProps, TimelineItemData, TimelineMarkerProps, TimelineContentProps, TimelineContextValue, TimelineItemContextValue, TimelineThemeOverrides, TimelineLayout, TimelineItemStatus } from "./Timeline.types";
 export { Timeline };
-export type { TimelineProps, TimelineItemProps, TimelineMarkerProps, TimelineContentProps, TimelineContextValue, TimelineItemContextValue, TimelineThemeOverrides, TimelineLayout, TimelineAlign, TimelineItemStatus, };
+export type { TimelineProps, TimelineItemProps, TimelineItemData, TimelineMarkerProps, TimelineContentProps, TimelineContextValue, TimelineItemContextValue, TimelineThemeOverrides, TimelineLayout, TimelineItemStatus, };

package/dist/components/effects/3d/index.d.ts

@@ -0,0 +1,4 @@
+export { AIOrb } from "../AIOrb";
+export type { AIOrbProps, OrbState, DotSphereProps, LiquidProps, AuraProps } from "../AIOrb";
+export { Particles } from "../Particles";
+export type { ParticlesProps } from "../Particles";

package/dist/components/effects/3d/index.js

@@ -0,0 +1,2 @@
+export { AIOrb } from '../AIOrb/AIOrb.js';
+export { Particles } from '../Particles/Particles.js';

package/dist/components/effects/AIOrb/AIOrb.d.ts

@@ -3,4 +3,5 @@ import type { AIOrbProps } from "./AIOrb.types";
 export declare const AIOrb: React.FC<AIOrbProps> & {
     DotSphere: React.FC<import("./variants").DotSphereProps>;
     Liquid: React.FC<import("./variants").LiquidProps>;
+    Aura: React.FC<import("./variants").AuraProps>;
 };

package/dist/components/effects/AIOrb/AIOrb.js

@@ -2,6 +2,7 @@ import { jsx } from 'react/jsx-runtime';
 import { cn } from '../../../utils/cn.js';
 import { DotSphere } from './variants/DotSphere/DotSphere.js';
 import { Liquid } from './variants/Liquid/Liquid.js';
+import { Aura } from './variants/Aura/Aura.js';
 
 const AIOrbRoot = ({ size, backgroundColor = "#000", className, style, children, ...props }) => {
     const containerStyle = {
@@ -9,8 +10,8 @@ const AIOrbRoot = ({ size, backgroundColor = "#000", className, style, children,
         ...(size ? { width: size, height: size } : {}),
         ...style,
     };
-    return (jsx("div", { className: cn("relative overflow-hidden", !size && "w-full h-full", className), style: containerStyle, ...props, children: children }));
+    return (jsx("div", { className: cn("relative overflow-visible", !size && "w-full h-full", className), style: containerStyle, ...props, children: children }));
 };
-const AIOrb = Object.assign(AIOrbRoot, { DotSphere, Liquid });
+const AIOrb = Object.assign(AIOrbRoot, { DotSphere, Liquid, Aura });
 
 export { AIOrb };

package/dist/components/effects/AIOrb/AIOrb.types.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+export type OrbState = "idle" | "listening" | "thinking" | "speaking";
 export interface AIOrbProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color"> {
     /**
      * Fixed size in pixels. If omitted the orb fills its parent.

package/dist/components/effects/AIOrb/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useOrbState } from "./useOrbState";
+export type { StateParamConfig } from "./useOrbState";

package/dist/components/effects/AIOrb/hooks/useOrbState.d.ts

@@ -0,0 +1,20 @@
+import type { OrbState } from "../AIOrb.types";
+/**
+ * State-to-parameter configuration. Maps each OrbState to a set of numeric
+ * target values that will be smoothly interpolated.
+ */
+export type StateParamConfig<T extends Record<string, number>> = Record<OrbState, T>;
+/**
+ * Generic ref-based interpolation hook for orb state-driven animation.
+ *
+ * - When `state` is defined, target values come from the config map.
+ * - When `state` is undefined, target values come from the `propValues` fallback
+ *   (backwards-compatible — orb behaves exactly as if no state was set).
+ * - Returns a mutable `valuesRef` read inside animation loops, and a `tick(dt)`
+ *   function that advances the interpolation by `dt` seconds.
+ * - Zero React re-renders — all mutation is ref-based.
+ */
+export declare function useOrbState<T extends Record<string, number>>(state: OrbState | undefined, config: StateParamConfig<T>, propValues: T, damping?: number): {
+    readonly valuesRef: import("react").RefObject<T>;
+    readonly tick: (dt: number) => void;
+};

package/dist/components/effects/AIOrb/hooks/useOrbState.js

@@ -0,0 +1,28 @@
+"use client";
+import { useRef, useCallback } from 'react';
+
+/**
+ * Generic ref-based interpolation hook for orb state-driven animation.
+ *
+ * - When `state` is defined, target values come from the config map.
+ * - When `state` is undefined, target values come from the `propValues` fallback
+ *   (backwards-compatible — orb behaves exactly as if no state was set).
+ * - Returns a mutable `valuesRef` read inside animation loops, and a `tick(dt)`
+ *   function that advances the interpolation by `dt` seconds.
+ * - Zero React re-renders — all mutation is ref-based.
+ */
+function useOrbState(state, config, propValues, damping = 4) {
+    const valuesRef = useRef({ ...propValues });
+    const tick = useCallback((dt) => {
+        const target = state ? config[state] : propValues;
+        const current = valuesRef.current;
+        const factor = 1 - Math.exp(-damping * dt);
+        for (const key in target) {
+            current[key] = (current[key] +
+                (target[key] - current[key]) * factor);
+        }
+    }, [state, config, propValues, damping]);
+    return { valuesRef, tick };
+}
+
+export { useOrbState };

package/dist/components/effects/AIOrb/index.d.ts

@@ -1,3 +1,3 @@
 export { AIOrb } from "./AIOrb";
-export type { AIOrbProps } from "./AIOrb.types";
-export type { DotSphereProps, LiquidProps } from "./variants";
+export type { AIOrbProps, OrbState } from "./AIOrb.types";
+export type { DotSphereProps, LiquidProps, AuraProps } from "./variants";

package/dist/components/effects/AIOrb/variants/Aura/Aura.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+import type { AuraProps } from "./Aura.types";
+export declare const Aura: React.FC<AuraProps>;

package/dist/components/effects/AIOrb/variants/Aura/Aura.js

@@ -0,0 +1,84 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+import { useMemo } from 'react';
+import { useReducedMotion } from 'motion/react';
+import { useIsClient } from '../../../../../hooks/useIsClient.js';
+import { useOrbState } from '../../hooks/useOrbState.js';
+import { ShaderCanvas } from '../../../shared/ShaderCanvas/ShaderCanvas.js';
+import { auraFragmentShader } from './Aura.shaders.js';
+
+const STATE_CONFIG = {
+    idle: { speed: 10, amplitude: 1.2, frequency: 0.4, brightness: 1.0, scale: 0.2 },
+    listening: { speed: 20, amplitude: 1.0, frequency: 0.7, brightness: 1.75, scale: 0.3 },
+    thinking: { speed: 30, amplitude: 0.5, frequency: 1.0, brightness: 1.5, scale: 0.3 },
+    speaking: { speed: 70, amplitude: 0.75, frequency: 1.25, brightness: 1.5, scale: 0.3 },
+};
+// ── Hex → RGB helper ─────────────────────────────────────────────────────────
+function hexToRgb(hex) {
+    const h = hex.replace("#", "");
+    const num = parseInt(h.length === 3 ? h.split("").map((c) => c + c).join("") : h, 16);
+    return [(num >> 16) / 255, ((num >> 8) & 0xff) / 255, (num & 0xff) / 255];
+}
+// ── Aura component ───────────────────────────────────────────────────────────
+const Aura = ({ color = "#1FD5F9", colorShift = 0.3, speed = 10, amplitude = 2.0, frequency = 0.5, scale = 0.2, blur = 1.0, brightness = 1.5, themeMode = "dark", state, }) => {
+    const isClient = useIsClient();
+    const shouldReduceMotion = useReducedMotion();
+    const rgb = useMemo(() => hexToRgb(color), [color]);
+    const propValues = useMemo(() => ({ speed, amplitude, frequency, brightness, scale }), [speed, amplitude, frequency, brightness, scale]);
+    const { valuesRef, tick } = useOrbState(state, STATE_CONFIG, propValues);
+    // Stable uniform object — mutated in-place each frame via the getter ref
+    const uniforms = useMemo(() => ({
+        u_color: rgb,
+        u_colorShift: colorShift,
+        u_speed: speed,
+        u_amplitude: amplitude,
+        u_frequency: frequency,
+        u_scale: scale,
+        u_blur: blur,
+        u_brightness: brightness,
+        u_bloom: 0.4,
+        u_spacing: 0.5,
+        u_variance: 0.1,
+        u_smoothing: 1.0,
+        u_lightMode: themeMode === "light" ? 1.0 : 0.0,
+    }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []);
+    // Sync non-interpolated props every render
+    uniforms.u_color = rgb;
+    uniforms.u_colorShift = colorShift;
+    uniforms.u_blur = blur;
+    uniforms.u_lightMode = themeMode === "light" ? 1.0 : 0.0;
+    // Custom ref whose getter ticks interpolation + writes interpolated values
+    // into the uniform object right before ShaderCanvas reads it each frame.
+    const tickingRef = useMemo(() => {
+        let lastT = 0;
+        return {
+            get current() {
+                const now = performance.now() / 1000;
+                if (lastT > 0) {
+                    tick(Math.min(now - lastT, 0.1));
+                }
+                lastT = now;
+                const v = valuesRef.current;
+                // u_speed is the shader's sole gate on iTime-driven motion (see
+                // Aura.shaders.ts: animTime = t * 0.1 * u_speed, the only place iTime
+                // reaches the turbulence). Zeroing it freezes the wave motion outright
+                // while amplitude/frequency/brightness/scale keep reflecting state.
+                uniforms.u_speed = shouldReduceMotion ? 0 : v.speed;
+                uniforms.u_amplitude = v.amplitude;
+                uniforms.u_frequency = v.frequency;
+                uniforms.u_brightness = v.brightness;
+                uniforms.u_scale = v.scale;
+                return uniforms;
+            },
+            set current(_v) {
+                // no-op — ShaderCanvas never writes to this ref
+            },
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [tick, shouldReduceMotion]);
+    return (jsx("div", { className: "absolute inset-0", "aria-hidden": "true", children: isClient && (jsx(ShaderCanvas, { fragmentShader: auraFragmentShader, uniformsRef: tickingRef })) }));
+};
+
+export { Aura };

package/dist/components/effects/AIOrb/variants/Aura/Aura.shaders.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Aura fragment shader — faithful port of LiveKit's AgentAudioVisualizerAura.
+ *
+ * Uses 36 iterations of turbulence-warped SDF evaluation to produce a
+ * luminous ring through accumulation. The ring shape emerges naturally
+ * from the turbulence + circle SDF interaction — not from drawing a
+ * ring directly.
+ *
+ * Uniforms (all from Aura component):
+ *   u_color       vec3  Base RGB colour (0-1)
+ *   u_colorShift  float HSV hue shift range across iterations (0-1)
+ *   u_speed       float Animation speed multiplier
+ *   u_amplitude   float Turbulence displacement strength
+ *   u_frequency   float Wave complexity (remapped to 2.0-15.0)
+ *   u_scale       float Circle SDF radius
+ *   u_blur        float Edge softness
+ *   u_brightness  float Overall brightness/opacity
+ *   u_bloom       float Glow intensity (dark mode only)
+ *   u_spacing     float Iteration spacing (remapped to 1.0-TAU)
+ *   u_variance    float Amplitude variance per turbulence layer
+ *   u_smoothing   float Dynamic blur smoothing factor
+ *   u_lightMode   float 0.0 = dark mode, 1.0 = light mode
+ *
+ * Built-in from ShaderCanvas:
+ *   iTime          float Elapsed seconds
+ *   iResolution    vec2  Viewport pixel dimensions
+ */
+export declare const auraFragmentShader = "#version 300 es\nprecision highp float;\n\nuniform float iTime;\nuniform vec2  iResolution;\n\nuniform vec3  u_color;\nuniform float u_colorShift;\nuniform float u_speed;\nuniform float u_amplitude;\nuniform float u_frequency;\nuniform float u_scale;\nuniform float u_blur;\nuniform float u_brightness;\nuniform float u_bloom;\nuniform float u_spacing;\nuniform float u_variance;\nuniform float u_smoothing;\nuniform float u_lightMode;\n\nout vec4 fragColor;\n\n/* \u2500\u2500 Constants \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\nconst float TAU = 6.283185;\n\n/* \u2500\u2500 Utilities \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\nvec2 randFibo(vec2 p) {\n  p = fract(p * vec2(443.897, 441.423));\n  p += dot(p, p.yx + 19.19);\n  return fract((p.xx + p.yx) * p.xy);\n}\n\nvec3 Tonemap(vec3 x) {\n  x *= 4.0;\n  return x / (1.0 + x);\n}\n\nfloat luma(vec3 color) {\n  return dot(color, vec3(0.299, 0.587, 0.114));\n}\n\nvec3 rgb2hsv(vec3 c) {\n  vec4 K = vec4(0.0, -1.0 / 3.0, 2.0 / 3.0, -1.0);\n  vec4 p = mix(vec4(c.bg, K.wz), vec4(c.gb, K.xy), step(c.b, c.g));\n  vec4 q = mix(vec4(p.xyw, c.r), vec4(c.r, p.yzx), step(p.x, c.r));\n  float d = q.x - min(q.w, q.y);\n  float e = 1.0e-10;\n  return vec3(abs(q.z + (q.w - q.y) / (6.0 * d + e)), d / (q.x + e), q.x);\n}\n\nvec3 hsv2rgb(vec3 c) {\n  vec4 K = vec4(1.0, 2.0 / 3.0, 1.0 / 3.0, 3.0);\n  vec3 p = abs(fract(c.xxx + K.xyz) * 6.0 - K.www);\n  return c.z * mix(K.xxx, clamp(p - K.xxx, 0.0, 1.0), c.y);\n}\n\n/* \u2500\u2500 SDF \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\nfloat sdCircle(vec2 st, float r) {\n  return length(st) - r;\n}\n\n/* \u2500\u2500 Turbulence \u2014 4 layers of sinusoidal displacement with rotation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\nvec2 turb(vec2 pos, float t, float it) {\n  mat2 rotation = mat2(0.6, -0.25, 0.25, 0.9);\n  mat2 layerRotation = mat2(0.6, -0.8, 0.8, 0.6);\n\n  float frequency = mix(2.0, 15.0, u_frequency);\n  float amplitude = u_amplitude;\n  float frequencyGrowth = 1.4;\n  float animTime = t * 0.1 * u_speed;\n\n  const int LAYERS = 4;\n  for (int i = 0; i < LAYERS; i++) {\n    vec2 rotatedPos = pos * rotation;\n    vec2 wave = sin(frequency * rotatedPos + float(i) * animTime + it);\n\n    pos += (amplitude / frequency) * rotation[0] * wave;\n\n    rotation *= layerRotation;\n    amplitude *= mix(1.0, max(wave.x, wave.y), u_variance);\n    frequency *= frequencyGrowth;\n  }\n\n  return pos;\n}\n\n/* \u2500\u2500 Main \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\nconst float ITERATIONS = 36.0;\n\nvoid main() {\n  vec2 uv = gl_FragCoord.xy / iResolution.xy;\n\n  vec3 pp = vec3(0.0);\n  vec3 bloom = vec3(0.0);\n  float t = iTime * 0.5;\n  vec2 pos = uv - 0.5;\n\n  vec2 prevPos = turb(pos, t, 0.0 - 1.0 / ITERATIONS);\n  float spacing = mix(1.0, TAU, u_spacing);\n\n  for (float i = 1.0; i < ITERATIONS + 1.0; i++) {\n    float iter = i / ITERATIONS;\n    vec2 st = turb(pos, t, iter * spacing);\n    float d = abs(sdCircle(st, u_scale));\n    float pd = distance(st, prevPos);\n    prevPos = st;\n    float dynamicBlur = exp2(pd * 2.0 * 1.4426950408889634) - 1.0;\n    float ds = smoothstep(0.0, u_blur * 0.05 + max(dynamicBlur * u_smoothing, 0.001), d);\n\n    vec3 col = u_color;\n    if (u_colorShift > 0.01) {\n      vec3 hsv = rgb2hsv(col);\n      hsv.x = fract(hsv.x + (1.0 - iter) * u_colorShift * 0.3);\n      col = hsv2rgb(hsv);\n    }\n\n    float invd = 1.0 / max(d + dynamicBlur, 0.001);\n    pp += (ds - 1.0) * col;\n    bloom += clamp(invd, 0.0, 250.0) * col;\n  }\n\n  pp *= 1.0 / ITERATIONS;\n\n  vec3 color;\n\n  // Dark mode (default)\n  if (u_lightMode < 0.5) {\n    bloom = bloom / (bloom + 2e4);\n    color = (-pp + bloom * 3.0 * u_bloom) * 1.2;\n    color += (randFibo(gl_FragCoord.xy).x - 0.5) / 255.0;\n    color = Tonemap(color);\n    float alpha = luma(color) * u_brightness;\n    fragColor = vec4(color * u_brightness, alpha);\n  }\n  // Light mode\n  else {\n    color = -pp;\n    color += (randFibo(gl_FragCoord.xy).x - 0.5) / 255.0;\n\n    float brightness = length(color);\n    vec3 direction = brightness > 0.0 ? color / brightness : color;\n\n    float factor = 2.0;\n    float mappedBrightness = (brightness * factor) / (1.0 + brightness * factor);\n    color = direction * mappedBrightness;\n\n    float gray = dot(color, vec3(0.2, 0.5, 0.1));\n    float saturationBoost = 3.0;\n    color = mix(vec3(gray), color, saturationBoost);\n\n    color = clamp(color, 0.0, 1.0);\n\n    float alpha = mappedBrightness * clamp(u_brightness, 1.0, 2.0);\n    fragColor = vec4(color, alpha);\n  }\n}\n";

package/dist/components/effects/AIOrb/variants/Aura/Aura.shaders.js

@@ -0,0 +1,191 @@
+/**
+ * Aura fragment shader — faithful port of LiveKit's AgentAudioVisualizerAura.
+ *
+ * Uses 36 iterations of turbulence-warped SDF evaluation to produce a
+ * luminous ring through accumulation. The ring shape emerges naturally
+ * from the turbulence + circle SDF interaction — not from drawing a
+ * ring directly.
+ *
+ * Uniforms (all from Aura component):
+ *   u_color       vec3  Base RGB colour (0-1)
+ *   u_colorShift  float HSV hue shift range across iterations (0-1)
+ *   u_speed       float Animation speed multiplier
+ *   u_amplitude   float Turbulence displacement strength
+ *   u_frequency   float Wave complexity (remapped to 2.0-15.0)
+ *   u_scale       float Circle SDF radius
+ *   u_blur        float Edge softness
+ *   u_brightness  float Overall brightness/opacity
+ *   u_bloom       float Glow intensity (dark mode only)
+ *   u_spacing     float Iteration spacing (remapped to 1.0-TAU)
+ *   u_variance    float Amplitude variance per turbulence layer
+ *   u_smoothing   float Dynamic blur smoothing factor
+ *   u_lightMode   float 0.0 = dark mode, 1.0 = light mode
+ *
+ * Built-in from ShaderCanvas:
+ *   iTime          float Elapsed seconds
+ *   iResolution    vec2  Viewport pixel dimensions
+ */
+const auraFragmentShader = `#version 300 es
+precision highp float;
+
+uniform float iTime;
+uniform vec2  iResolution;
+
+uniform vec3  u_color;
+uniform float u_colorShift;
+uniform float u_speed;
+uniform float u_amplitude;
+uniform float u_frequency;
+uniform float u_scale;
+uniform float u_blur;
+uniform float u_brightness;
+uniform float u_bloom;
+uniform float u_spacing;
+uniform float u_variance;
+uniform float u_smoothing;
+uniform float u_lightMode;
+
+out vec4 fragColor;
+
+/* ── Constants ─────────────────────────────────────────────────────────────── */
+
+const float TAU = 6.283185;
+
+/* ── Utilities ─────────────────────────────────────────────────────────────── */
+
+vec2 randFibo(vec2 p) {
+  p = fract(p * vec2(443.897, 441.423));
+  p += dot(p, p.yx + 19.19);
+  return fract((p.xx + p.yx) * p.xy);
+}
+
+vec3 Tonemap(vec3 x) {
+  x *= 4.0;
+  return x / (1.0 + x);
+}
+
+float luma(vec3 color) {
+  return dot(color, vec3(0.299, 0.587, 0.114));
+}
+
+vec3 rgb2hsv(vec3 c) {
+  vec4 K = vec4(0.0, -1.0 / 3.0, 2.0 / 3.0, -1.0);
+  vec4 p = mix(vec4(c.bg, K.wz), vec4(c.gb, K.xy), step(c.b, c.g));
+  vec4 q = mix(vec4(p.xyw, c.r), vec4(c.r, p.yzx), step(p.x, c.r));
+  float d = q.x - min(q.w, q.y);
+  float e = 1.0e-10;
+  return vec3(abs(q.z + (q.w - q.y) / (6.0 * d + e)), d / (q.x + e), q.x);
+}
+
+vec3 hsv2rgb(vec3 c) {
+  vec4 K = vec4(1.0, 2.0 / 3.0, 1.0 / 3.0, 3.0);
+  vec3 p = abs(fract(c.xxx + K.xyz) * 6.0 - K.www);
+  return c.z * mix(K.xxx, clamp(p - K.xxx, 0.0, 1.0), c.y);
+}
+
+/* ── SDF ───────────────────────────────────────────────────────────────────── */
+
+float sdCircle(vec2 st, float r) {
+  return length(st) - r;
+}
+
+/* ── Turbulence — 4 layers of sinusoidal displacement with rotation ────────── */
+
+vec2 turb(vec2 pos, float t, float it) {
+  mat2 rotation = mat2(0.6, -0.25, 0.25, 0.9);
+  mat2 layerRotation = mat2(0.6, -0.8, 0.8, 0.6);
+
+  float frequency = mix(2.0, 15.0, u_frequency);
+  float amplitude = u_amplitude;
+  float frequencyGrowth = 1.4;
+  float animTime = t * 0.1 * u_speed;
+
+  const int LAYERS = 4;
+  for (int i = 0; i < LAYERS; i++) {
+    vec2 rotatedPos = pos * rotation;
+    vec2 wave = sin(frequency * rotatedPos + float(i) * animTime + it);
+
+    pos += (amplitude / frequency) * rotation[0] * wave;
+
+    rotation *= layerRotation;
+    amplitude *= mix(1.0, max(wave.x, wave.y), u_variance);
+    frequency *= frequencyGrowth;
+  }
+
+  return pos;
+}
+
+/* ── Main ──────────────────────────────────────────────────────────────────── */
+
+const float ITERATIONS = 36.0;
+
+void main() {
+  vec2 uv = gl_FragCoord.xy / iResolution.xy;
+
+  vec3 pp = vec3(0.0);
+  vec3 bloom = vec3(0.0);
+  float t = iTime * 0.5;
+  vec2 pos = uv - 0.5;
+
+  vec2 prevPos = turb(pos, t, 0.0 - 1.0 / ITERATIONS);
+  float spacing = mix(1.0, TAU, u_spacing);
+
+  for (float i = 1.0; i < ITERATIONS + 1.0; i++) {
+    float iter = i / ITERATIONS;
+    vec2 st = turb(pos, t, iter * spacing);
+    float d = abs(sdCircle(st, u_scale));
+    float pd = distance(st, prevPos);
+    prevPos = st;
+    float dynamicBlur = exp2(pd * 2.0 * 1.4426950408889634) - 1.0;
+    float ds = smoothstep(0.0, u_blur * 0.05 + max(dynamicBlur * u_smoothing, 0.001), d);
+
+    vec3 col = u_color;
+    if (u_colorShift > 0.01) {
+      vec3 hsv = rgb2hsv(col);
+      hsv.x = fract(hsv.x + (1.0 - iter) * u_colorShift * 0.3);
+      col = hsv2rgb(hsv);
+    }
+
+    float invd = 1.0 / max(d + dynamicBlur, 0.001);
+    pp += (ds - 1.0) * col;
+    bloom += clamp(invd, 0.0, 250.0) * col;
+  }
+
+  pp *= 1.0 / ITERATIONS;
+
+  vec3 color;
+
+  // Dark mode (default)
+  if (u_lightMode < 0.5) {
+    bloom = bloom / (bloom + 2e4);
+    color = (-pp + bloom * 3.0 * u_bloom) * 1.2;
+    color += (randFibo(gl_FragCoord.xy).x - 0.5) / 255.0;
+    color = Tonemap(color);
+    float alpha = luma(color) * u_brightness;
+    fragColor = vec4(color * u_brightness, alpha);
+  }
+  // Light mode
+  else {
+    color = -pp;
+    color += (randFibo(gl_FragCoord.xy).x - 0.5) / 255.0;
+
+    float brightness = length(color);
+    vec3 direction = brightness > 0.0 ? color / brightness : color;
+
+    float factor = 2.0;
+    float mappedBrightness = (brightness * factor) / (1.0 + brightness * factor);
+    color = direction * mappedBrightness;
+
+    float gray = dot(color, vec3(0.2, 0.5, 0.1));
+    float saturationBoost = 3.0;
+    color = mix(vec3(gray), color, saturationBoost);
+
+    color = clamp(color, 0.0, 1.0);
+
+    float alpha = mappedBrightness * clamp(u_brightness, 1.0, 2.0);
+    fragColor = vec4(color, alpha);
+  }
+}
+`;
+
+export { auraFragmentShader };

package/dist/components/effects/AIOrb/variants/Aura/Aura.types.d.ts

@@ -0,0 +1,53 @@
+import type { OrbState } from "../../AIOrb.types";
+export interface AuraProps {
+    /**
+     * Base colour as a hex string.
+     * @default '#1FD5F9'
+     */
+    color?: string;
+    /**
+     * HSV hue shift for iridescence (0-1).
+     * @default 0.3
+     */
+    colorShift?: number;
+    /**
+     * Animation speed multiplier.
+     * @default 10
+     */
+    speed?: number;
+    /**
+     * Wave displacement strength.
+     * @default 2.0
+     */
+    amplitude?: number;
+    /**
+     * Wave complexity.
+     * @default 0.5
+     */
+    frequency?: number;
+    /**
+     * Circle SDF radius in normalized coordinates.
+     * @default 0.2
+     */
+    scale?: number;
+    /**
+     * Edge softness.
+     * @default 1.0
+     */
+    blur?: number;
+    /**
+     * Overall brightness/opacity.
+     * @default 1.5
+     */
+    brightness?: number;
+    /**
+     * Rendering mode — affects colour inversion for light backgrounds.
+     * @default 'dark'
+     */
+    themeMode?: "dark" | "light";
+    /**
+     * State-driven animation. When set, overrides speed/amplitude/frequency/
+     * brightness/scale with smooth interpolation towards state targets.
+     */
+    state?: OrbState;
+}

package/dist/components/effects/AIOrb/variants/Aura/index.d.ts

@@ -0,0 +1,2 @@
+export { Aura } from "./Aura";
+export type { AuraProps } from "./Aura.types";

package/dist/components/effects/AIOrb/variants/DotSphere/DotSphere.d.ts

@@ -1,3 +1,10 @@
 import React from "react";
 import type { DotSphereProps } from "./DotSphere.types";
+/**
+ * Lazy-loading shell. The actual scene (`OrbScene` + `<Canvas>`) lives in
+ * `DotSphere.impl`, which imports `@react-three/fiber` and `three` — dynamically
+ * imported here on mount so that rendering a sibling AIOrb variant that doesn't
+ * need three (e.g. `AIOrb.Aura`, raw WebGL) never pulls that bundle in. Mirrors
+ * `TiltCard`'s `glow` lazy-load (see `TiltCard.tsx` / `TiltCard.glow.ts`).
+ */
 export declare const DotSphere: React.FC<DotSphereProps>;