@backbay/glia-three 0.2.0-alpha.2

package/src/three/Sentinel/SentinelTether.tsx

@@ -0,0 +1,182 @@
+'use client';
+
+/**
+ * SentinelTether
+ *
+ * An SVG line connecting the Sentinel orb to its taskbar origin.
+ * Visible during summoning phase, fades out during open phase.
+ */
+
+import { motion } from 'framer-motion';
+import React from 'react';
+
+import { useSentinelStore } from './sentinelStore';
+
+export const SentinelTether: React.FC = () => {
+  const phase = useSentinelStore((s) => s.phase);
+  const orbPosition = useSentinelStore((s) => s.orbPosition);
+  const taskbarOrigin = useSentinelStore((s) => s.taskbarOrigin);
+
+  const start = taskbarOrigin;
+  const end = orbPosition;
+  const dx = end.x - start.x;
+  const dy = end.y - start.y;
+  const distance = Math.hypot(dx, dy);
+  const safeDistance = distance || 1;
+  const normal = { x: -dy / safeDistance, y: dx / safeDistance };
+  const steps = Math.max(6, Math.min(24, Math.round(safeDistance / 28)));
+  const baseAmp = Math.min(5.5, Math.max(1.5, safeDistance * 0.015));
+  const jitterSeed = Math.sin((start.x + start.y) * 0.015);
+  const freq = 3 + Math.floor(safeDistance / 160);
+  const points = Array.from({ length: steps + 1 }, (_, index) => {
+    const t = steps === 0 ? 0 : index / steps;
+    let offset = 0;
+    if (index > 0 && index < steps) {
+      const phaseA = t * Math.PI * (2 + freq) + jitterSeed * 2.7;
+      const phaseB = t * Math.PI * (3.5 + freq * 1.4) + jitterSeed * 4.1;
+      const wobble = Math.sin(phaseA);
+      const chisel = Math.sign(Math.sin(phaseB));
+      const amp = baseAmp * (0.45 + 0.55 * Math.sin(t * Math.PI * 2 + jitterSeed));
+      offset = (wobble * 0.6 + chisel * 0.4) * amp;
+      offset = Math.round(offset * 2) / 2;
+    }
+    return {
+      x: start.x + dx * t + normal.x * offset,
+      y: start.y + dy * t + normal.y * offset,
+    };
+  });
+  const pointsAttr = points.map((point) => `${point.x},${point.y}`).join(' ');
+  const dash = Math.max(10, Math.min(24, safeDistance * 0.115));
+  const gap = Math.max(16, Math.min(34, safeDistance * 0.19));
+  const dashArray = `${dash} ${gap}`;
+  const sparkDashArray = `${Math.max(2.5, dash * 0.35)} ${Math.max(10, gap * 1.4)}`;
+
+  // Only render during summoning or open phases
+  if (phase === 'docked' || phase === 'dismissing' || phase === 'throwing' || phase === 'avatar') {
+    return null;
+  }
+
+  // Determine opacity based on phase
+  const targetOpacity = phase === 'summoning' ? 1 : 0;
+  const gradientId = 'sentinel-tether-gradient';
+  const filterId = 'sentinel-tether-glow';
+
+  return (
+    <svg
+      style={{
+        position: 'fixed',
+        inset: 0,
+        width: '100%',
+        height: '100%',
+        pointerEvents: 'none',
+        zIndex: 9998,
+      }}
+    >
+      <defs>
+        {/* Linear gradient from gold core to warm flare */}
+        <linearGradient
+          id={gradientId}
+          x1={taskbarOrigin.x}
+          y1={taskbarOrigin.y}
+          x2={orbPosition.x}
+          y2={orbPosition.y}
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset="0%" stopColor="#9f6420" stopOpacity={0.95} />
+          <stop offset="15%" stopColor="#e1a341" stopOpacity={0.98} />
+          <stop offset="35%" stopColor="#ffd48a" stopOpacity={0.95} />
+          <stop offset="55%" stopColor="#fff0c9" stopOpacity={0.9} />
+          <stop offset="75%" stopColor="#efb95f" stopOpacity={0.78} />
+          <stop offset="100%" stopColor="#b9792a" stopOpacity={0.5} />
+        </linearGradient>
+
+        {/* Glow filter */}
+        <filter id={filterId} x="-90%" y="-90%" width="280%" height="280%">
+          <feGaussianBlur in="SourceGraphic" stdDeviation="3.6" result="blur" />
+          <feColorMatrix
+            type="matrix"
+            values="
+              1 0 0 0 0
+              0 0.85 0 0 0
+              0 0 0.45 0 0
+              0 0 0 1 0"
+            result="glow"
+          />
+          <feMerge>
+            <feMergeNode in="glow" />
+            <feMergeNode in="SourceGraphic" />
+          </feMerge>
+        </filter>
+      </defs>
+
+      <motion.polyline
+        points={pointsAttr}
+        stroke="rgba(212, 168, 75, 0.32)"
+        strokeWidth={4.1}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        fill="none"
+        filter={`url(#${filterId})`}
+        initial={{ opacity: 0.8 }}
+        animate={{ opacity: targetOpacity }}
+        transition={{ duration: 0.75, ease: 'easeOut' }}
+      />
+      <motion.polyline
+        points={pointsAttr}
+        stroke={`url(#${gradientId})`}
+        strokeWidth={2.4}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        fill="none"
+        filter={`url(#${filterId})`}
+        initial={{ opacity: 1 }}
+        animate={{ opacity: targetOpacity }}
+        transition={{ duration: 0.75, ease: 'easeOut' }}
+      />
+      <motion.polyline
+        points={pointsAttr}
+        stroke="rgba(255, 234, 184, 0.9)"
+        strokeWidth={1.05}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        fill="none"
+        strokeDasharray={dashArray}
+        filter={`url(#${filterId})`}
+        initial={{ opacity: 0.55, strokeDashoffset: 0 }}
+        animate={{ opacity: targetOpacity, strokeDashoffset: -safeDistance }}
+        transition={{
+          opacity: { duration: 0.75, ease: 'easeOut' },
+          strokeDashoffset: { duration: 7.8, repeat: Infinity, ease: 'linear' },
+        }}
+      />
+      <motion.polyline
+        points={pointsAttr}
+        stroke="rgba(255, 241, 210, 0.9)"
+        strokeWidth={0.8}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        fill="none"
+        strokeDasharray={sparkDashArray}
+        filter={`url(#${filterId})`}
+        initial={{ opacity: 0.35, strokeDashoffset: 0 }}
+        animate={{ opacity: targetOpacity, strokeDashoffset: -safeDistance * 1.6 }}
+        transition={{
+          opacity: { duration: 0.75, ease: 'easeOut' },
+          strokeDashoffset: { duration: 10.6, repeat: Infinity, ease: 'linear' },
+        }}
+      />
+      <motion.circle
+        cx={orbPosition.x}
+        cy={orbPosition.y}
+        r={5}
+        fill="rgba(212, 168, 75, 0.9)"
+        filter={`url(#${filterId})`}
+        initial={{ opacity: 0.6, scale: 1 }}
+        animate={{ opacity: targetOpacity, scale: [1, 1.18, 1] }}
+        transition={{ duration: 3.4, repeat: Infinity, ease: 'easeInOut' }}
+      />
+    </svg>
+  );
+};
+
+export default SentinelTether;

package/src/three/Sentinel/SigilPlaceholder.tsx

@@ -0,0 +1,176 @@
+'use client';
+
+import { useFrame } from '@react-three/fiber';
+import React, { useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import type { Group } from 'three';
+
+const RING_SEGMENTS = 64;
+const TICK_COUNT = 16;
+const RUNE_COUNT = 28;
+
+export const SigilPlaceholder: React.FC<{ scale?: number }> = ({ scale = 1 }) => {
+  const groupRef = useRef<Group>(null);
+  const runeRef = useRef<Group>(null);
+  const shimmerRef = useRef<THREE.MeshBasicMaterial | null>(null);
+  const ticks = useMemo(() => Array.from({ length: TICK_COUNT }, (_, i) => i), []);
+  const runes = useMemo(
+    () =>
+      Array.from({ length: RUNE_COUNT }, (_, i) => {
+        const angle = (i / RUNE_COUNT) * Math.PI * 2;
+        const width = 0.028 + 0.014 * Math.abs(Math.sin(i * 1.7));
+        const height = 0.007 + 0.01 * Math.abs(Math.cos(i * 1.3));
+        const opacity = 0.18 + 0.12 * Math.abs(Math.sin(i * 0.9));
+        return { i, angle, width, height, opacity };
+      }),
+    []
+  );
+  const noiseTexture = useMemo(() => {
+    const size = 64;
+    const data = new Uint8Array(size * size * 4);
+    for (let i = 0; i < size * size; i += 1) {
+      const intensity = 130 + Math.floor(Math.random() * 125);
+      data[i * 4] = intensity;
+      data[i * 4 + 1] = Math.min(255, intensity + 40);
+      data[i * 4 + 2] = 30;
+      data[i * 4 + 3] = 120 + Math.floor(Math.random() * 120);
+    }
+    const tex = new THREE.DataTexture(data, size, size, THREE.RGBAFormat);
+    tex.wrapS = THREE.RepeatWrapping;
+    tex.wrapT = THREE.RepeatWrapping;
+    tex.repeat.set(4, 4);
+    tex.needsUpdate = true;
+    return tex;
+  }, []);
+
+  useFrame((_, delta) => {
+    if (!groupRef.current) return;
+    groupRef.current.rotation.z += delta * 0.25;
+    groupRef.current.rotation.x = 0.12;
+    if (runeRef.current) {
+      runeRef.current.rotation.z -= delta * 0.08;
+    }
+    if (shimmerRef.current?.map) {
+      shimmerRef.current.map.offset.x =
+        (shimmerRef.current.map.offset.x + delta * 0.08) % 1;
+      shimmerRef.current.map.offset.y =
+        (shimmerRef.current.map.offset.y + delta * 0.05) % 1;
+      shimmerRef.current.opacity = 0.12 + Math.sin(Date.now() * 0.002) * 0.03;
+    }
+  });
+
+  return (
+    <group ref={groupRef} scale={scale}>
+      <mesh rotation={[Math.PI / 2, 0, 0]}>
+        <ringGeometry args={[0.62, 0.66, RING_SEGMENTS]} />
+        <meshStandardMaterial
+          color="#d4a84b"
+          emissive="#d4a84b"
+          emissiveIntensity={0.35}
+          transparent
+          opacity={0.6}
+          metalness={0.4}
+          roughness={0.3}
+          toneMapped={false}
+        />
+      </mesh>
+      <mesh rotation={[Math.PI / 2, 0, 0]}>
+        <ringGeometry args={[0.44, 0.455, RING_SEGMENTS]} />
+        <meshStandardMaterial
+          color="#f2c96b"
+          emissive="#f2c96b"
+          emissiveIntensity={0.4}
+          transparent
+          opacity={0.7}
+          metalness={0.35}
+          roughness={0.35}
+          toneMapped={false}
+        />
+      </mesh>
+      <mesh rotation={[Math.PI / 2, 0, 0]}>
+        <ringGeometry args={[0.32, 0.7, RING_SEGMENTS]} />
+        <meshBasicMaterial
+          ref={shimmerRef}
+          map={noiseTexture}
+          color="#f2c96b"
+          transparent
+          opacity={0.14}
+          blending={THREE.AdditiveBlending}
+          depthWrite={false}
+          toneMapped={false}
+        />
+      </mesh>
+      <mesh rotation={[0, 0, 0]}>
+        <torusGeometry args={[0.22, 0.01, 12, 96]} />
+        <meshStandardMaterial
+          color="#6b8cbe"
+          emissive="#9bb4e3"
+          emissiveIntensity={0.35}
+          transparent
+          opacity={0.6}
+          metalness={0.2}
+          roughness={0.2}
+          toneMapped={false}
+        />
+      </mesh>
+      <mesh rotation={[Math.PI / 2, 0, 0]}>
+        <ringGeometry args={[0.12, 0.125, 32]} />
+        <meshStandardMaterial
+          color="#e6d3a3"
+          emissive="#f2c96b"
+          emissiveIntensity={0.4}
+          transparent
+          opacity={0.7}
+          metalness={0.4}
+          roughness={0.3}
+          toneMapped={false}
+        />
+      </mesh>
+      <group ref={runeRef}>
+        {runes.map((rune) => {
+          const x = Math.cos(rune.angle) * 0.52;
+          const y = Math.sin(rune.angle) * 0.52;
+          return (
+            <mesh
+              key={`rune-${rune.i}`}
+              position={[x, y, 0]}
+              rotation={[0, 0, rune.angle]}
+            >
+              <boxGeometry args={[rune.width, rune.height, 0.01]} />
+              <meshBasicMaterial
+                color="#d4a84b"
+                transparent
+                opacity={rune.opacity}
+                blending={THREE.AdditiveBlending}
+                depthWrite={false}
+                toneMapped={false}
+              />
+            </mesh>
+          );
+        })}
+      </group>
+      {ticks.map((i) => {
+        const angle = (i / TICK_COUNT) * Math.PI * 2;
+        const x = Math.cos(angle) * 0.74;
+        const y = Math.sin(angle) * 0.74;
+        return (
+          <mesh key={`tick-${i}`} position={[x, y, 0]} rotation={[0, 0, angle]}>
+            <boxGeometry args={[0.06, 0.012, 0.01]} />
+            <meshStandardMaterial
+              color="#d4a84b"
+              emissive="#d4a84b"
+              emissiveIntensity={0.3}
+              transparent
+              opacity={0.6}
+              metalness={0.3}
+              roughness={0.4}
+              toneMapped={false}
+            />
+          </mesh>
+        );
+      })}
+    </group>
+  );
+};
+
+export default SigilPlaceholder;

package/src/three/Sentinel/VerticalSubmenu.tsx

@@ -0,0 +1,150 @@
+'use client';
+
+/**
+ * VerticalSubmenu
+ *
+ * A vertical dropdown submenu that appears when hovering over a radial submenu item
+ * that has children. Supports scrolling for many items.
+ */
+
+import { motion } from 'framer-motion';
+import React, { useEffect, useState } from 'react';
+import styled from 'styled-components';
+
+import type { VerticalSubmenuProps, SubmenuItem } from './types';
+import { useSentinelDependencies } from './SentinelProvider';
+
+const ITEM_HEIGHT = 36;
+const MAX_VISIBLE_ITEMS = 6;
+const MENU_WIDTH = 160;
+const PADDING_Y = 4;
+
+const Container = styled(motion.div)<{ $openUpward: boolean }>`
+  position: fixed;
+  width: ${MENU_WIDTH}px;
+  max-height: ${ITEM_HEIGHT * MAX_VISIBLE_ITEMS + PADDING_Y * 2}px;
+  overflow-y: auto;
+  background: rgba(0, 0, 0, 0.85);
+  backdrop-filter: blur(12px);
+  border: 1px solid rgba(212, 168, 75, 0.25);
+  border-radius: 8px;
+  padding: ${PADDING_Y}px 0;
+  transform-origin: ${({ $openUpward }: { $openUpward: boolean }) => ($openUpward ? 'bottom center' : 'top center')};
+  z-index: 10000;
+
+  /* Custom scrollbar */
+  &::-webkit-scrollbar {
+    width: 4px;
+  }
+
+  &::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  &::-webkit-scrollbar-thumb {
+    background: rgba(212, 168, 75, 0.3);
+    border-radius: 2px;
+  }
+
+  &::-webkit-scrollbar-thumb:hover {
+    background: rgba(212, 168, 75, 0.5);
+  }
+`;
+
+const ItemRow = styled(motion.button)`
+  width: 100%;
+  height: ${ITEM_HEIGHT}px;
+  padding: 8px 12px;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  background: transparent;
+  border: none;
+  border-left: 2px solid transparent;
+  cursor: pointer;
+  outline: none;
+  transition:
+    background 0.15s ease,
+    border-color 0.15s ease;
+
+  &:not(:last-child) {
+    border-bottom: 1px solid rgba(212, 168, 75, 0.1);
+  }
+
+  &:hover {
+    background: rgba(212, 168, 75, 0.1);
+    border-left-color: rgba(212, 168, 75, 0.9);
+  }
+`;
+
+const ItemLabel = styled.span`
+  font-family: var(--font-mono);
+  font-size: 10px;
+  letter-spacing: 0.08em;
+  color: rgba(212, 168, 75, 0.9);
+  text-transform: uppercase;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+`;
+
+export const VerticalSubmenu: React.FC<VerticalSubmenuProps> = ({
+  items,
+  anchorPosition,
+  onItemClick,
+}) => {
+  const [openUpward, setOpenUpward] = useState(false);
+  const { IconRenderer } = useSentinelDependencies();
+
+  useEffect(() => {
+    const menuHeight = Math.min(items.length, MAX_VISIBLE_ITEMS) * ITEM_HEIGHT + PADDING_Y * 2;
+    const spaceBelow = typeof window !== 'undefined'
+      ? window.innerHeight - anchorPosition.y
+      : 600 - anchorPosition.y;
+    setOpenUpward(spaceBelow < menuHeight + 20);
+  }, [anchorPosition.y, items.length]);
+
+  const windowHeight = typeof window !== 'undefined' ? window.innerHeight : 600;
+
+  const style: React.CSSProperties = {
+    left: anchorPosition.x - MENU_WIDTH / 2,
+    ...(openUpward
+      ? { bottom: windowHeight - anchorPosition.y }
+      : { top: anchorPosition.y }),
+  };
+
+  return (
+    <Container
+      $openUpward={openUpward}
+      style={style}
+      initial={{ scaleY: 0, opacity: 0 }}
+      animate={{ scaleY: 1, opacity: 1 }}
+      exit={{ scaleY: 0, opacity: 0 }}
+      transition={{ duration: 0.2, ease: [0.4, 0, 0.2, 1] }}
+    >
+      {items.map((item, index) => (
+        <ItemRow
+          key={item.id}
+          onClick={() => {
+            item.action?.();
+            onItemClick(item);
+          }}
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+          transition={{ delay: index * 0.03, duration: 0.15 }}
+        >
+          {IconRenderer && (
+            <IconRenderer
+              name={item.icon}
+              size={16}
+              color="rgba(212, 168, 75, 0.9)"
+            />
+          )}
+          <ItemLabel>{item.label}</ItemLabel>
+        </ItemRow>
+      ))}
+    </Container>
+  );
+};
+
+export default VerticalSubmenu;

package/src/three/Sentinel/index.ts

@@ -0,0 +1,145 @@
+/**
+ * Sentinel - A floating orb UI component system
+ *
+ * The Sentinel is a radial menu system that can be summoned, thrown, and docked.
+ * It provides quick access to applications and features through a cardinal
+ * direction-based menu with optional radial and vertical submenus.
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   SentinelProvider,
+ *   SentinelOverlay,
+ *   DockedMiniOrb,
+ *   useSentinelStore,
+ * } from '@backbay/glia';
+ *
+ * // In your app root or layout:
+ * function App() {
+ *   return (
+ *     <SentinelProvider
+ *       dependencies={{
+ *         IconRenderer: MyIconComponent,
+ *         GlyphRenderer: MyGlyphComponent,
+ *         onOpenProcess: (id, opts) => openApp(id, opts),
+ *         processMap: { console: 'terminal', lens: 'viewer' },
+ *       }}
+ *     >
+ *       <SentinelOverlay />
+ *       <DockedMiniOrb />
+ *       {children}
+ *     </SentinelProvider>
+ *   );
+ * }
+ *
+ * // In your taskbar:
+ * function TaskbarItem() {
+ *   const summon = useSentinelStore((s) => s.summon);
+ *   const setTaskbarOrigin = useSentinelStore((s) => s.setTaskbarOrigin);
+ *
+ *   const handleClick = (e: React.MouseEvent) => {
+ *     const rect = e.currentTarget.getBoundingClientRect();
+ *     setTaskbarOrigin({ x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 });
+ *     summon();
+ *   };
+ *
+ *   return <button onClick={handleClick}>Sentinel</button>;
+ * }
+ * ```
+ */
+
+// -----------------------------------------------------------------------------
+// Core Components
+// -----------------------------------------------------------------------------
+
+export { SentinelOverlay } from './SentinelOverlay';
+export { SentinelOrb } from './SentinelOrb';
+export { SentinelTether } from './SentinelTether';
+export { DockedMiniOrb } from './DockedMiniOrb';
+
+// -----------------------------------------------------------------------------
+// Menu Components
+// -----------------------------------------------------------------------------
+
+export { CardinalMenu } from './CardinalMenu';
+export { CardinalItem } from './CardinalItem';
+export { RadialSubmenu } from './RadialSubmenu';
+export { VerticalSubmenu } from './VerticalSubmenu';
+
+// -----------------------------------------------------------------------------
+// Conversation Components
+// -----------------------------------------------------------------------------
+
+export { SentinelConversation } from './SentinelConversation';
+
+// -----------------------------------------------------------------------------
+// Avatar Components
+// -----------------------------------------------------------------------------
+
+export { AvatarMode } from './AvatarMode';
+export { AvatarRenderer } from './AvatarRenderer';
+export { CameraPip } from './CameraPip';
+
+// -----------------------------------------------------------------------------
+// Hooks
+// -----------------------------------------------------------------------------
+
+export { useThrowPhysics } from './useThrowPhysics';
+export { useCameraPermission } from './useCameraPermission';
+
+// -----------------------------------------------------------------------------
+// Provider and Context
+// -----------------------------------------------------------------------------
+
+export { SentinelProvider, useSentinelDependencies } from './SentinelProvider';
+
+// -----------------------------------------------------------------------------
+// Store
+// -----------------------------------------------------------------------------
+
+export { useSentinelStore, createSentinelStore, type SentinelStoreApi } from './sentinelStore';
+
+// -----------------------------------------------------------------------------
+// Types
+// -----------------------------------------------------------------------------
+
+export type {
+  // Core types
+  SentinelPhase,
+  Edge,
+  DockedPosition,
+  Cardinal,
+  ConversationState,
+  DocketItem,
+  OrbPosition,
+  SentinelState,
+
+  // Component props
+  SentinelDependencies,
+  SentinelOverlayProps,
+  SentinelOrbProps,
+  SentinelTetherProps,
+  CardinalMenuProps,
+  CardinalItemProps,
+  SubmenuItem,
+  ArcConstraint,
+  RadialSubmenuProps,
+  VerticalSubmenuProps,
+  DockedMiniOrbProps,
+  AvatarModeProps,
+  AvatarRendererProps,
+  CameraPipProps,
+
+  // Avatar types
+  AvatarMotionData,
+  AvatarSessionReturn,
+
+  // Hook types
+  UseCameraPermissionReturn,
+  ThrowPhysicsOptions,
+  ThrowPhysicsReturn,
+
+  // Provider types
+  SentinelProviderProps,
+  SentinelContextValue,
+} from './types';