vibecarbon 0.1.0

package/carbon/src/client/hooks/usePackageManager.ts

@@ -0,0 +1,69 @@
+import { useCallback, useSyncExternalStore } from 'react';
+
+export type PackageManager = 'pnpm' | 'npm' | 'bun';
+
+const STORAGE_KEY = 'docs-package-manager';
+const DEFAULT_PM: PackageManager = 'pnpm';
+const VALID: Set<string> = new Set(['pnpm', 'npm', 'bun']);
+
+// Tiny external store so every hook instance shares the same value
+let current: PackageManager = (() => {
+  try {
+    const v = localStorage.getItem(STORAGE_KEY);
+    return v && VALID.has(v) ? (v as PackageManager) : DEFAULT_PM;
+  } catch {
+    return DEFAULT_PM;
+  }
+})();
+
+const listeners = new Set<() => void>();
+function subscribe(cb: () => void) {
+  listeners.add(cb);
+  return () => listeners.delete(cb);
+}
+function getSnapshot() {
+  return current;
+}
+
+function setPm(pm: PackageManager) {
+  current = pm;
+  try {
+    localStorage.setItem(STORAGE_KEY, pm);
+  } catch {}
+  for (const cb of listeners) cb();
+}
+
+export function usePackageManager() {
+  const pm = useSyncExternalStore(subscribe, getSnapshot, () => DEFAULT_PM);
+  const set = useCallback((v: PackageManager) => setPm(v), []);
+  return [pm, set] as const;
+}
+
+// npm lifecycle scripts that don't need "run"
+const npmLifecycle = new Set(['test', 'start', 'stop', 'restart', 'install']);
+
+export function replacePackageManager(text: string, pm: PackageManager): string {
+  if (pm === 'pnpm') return text;
+
+  // Replace "pnpm dlx" → "npx" / "bunx"
+  text = text.replace(/\bpnpm dlx\b/g, () => {
+    if (pm === 'npm') return 'npx';
+    return 'bunx';
+  });
+
+  // Replace "pnpm <subcommand>" patterns
+  text = text.replace(/\bpnpm (\S+)/g, (_match, sub: string) => {
+    if (pm === 'npm') {
+      // npm lifecycle shorthands don't need "run"
+      if (npmLifecycle.has(sub)) return `npm ${sub}`;
+      return `npm run ${sub}`;
+    }
+    // bun is a direct swap
+    return `${pm} ${sub}`;
+  });
+
+  // Replace any remaining standalone "pnpm"
+  text = text.replace(/\bpnpm\b/g, pm === 'npm' ? 'npm' : pm);
+
+  return text;
+}

package/carbon/src/client/hooks/useReducedMotion.ts

@@ -0,0 +1,20 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Hook to detect user's reduced motion preference
+ * Respects accessibility settings for users who prefer less animation
+ */
+export function useReducedMotion(): boolean {
+  const [prefersReducedMotion, setPrefersReducedMotion] = useState(false);
+
+  useEffect(() => {
+    const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+    setPrefersReducedMotion(mediaQuery.matches);
+
+    const handler = (e: MediaQueryListEvent) => setPrefersReducedMotion(e.matches);
+    mediaQuery.addEventListener('change', handler);
+    return () => mediaQuery.removeEventListener('change', handler);
+  }, []);
+
+  return prefersReducedMotion;
+}

package/carbon/src/client/hooks/useRunningServices.ts

@@ -0,0 +1,114 @@
+import { useQuery } from '@tanstack/react-query';
+import { adminServices } from '@/lib/admin-services';
+import { getAuthHeaders } from '@/lib/api';
+
+interface ServiceStatus {
+  name: string;
+  container: string;
+  status: 'healthy' | 'unhealthy' | 'unknown';
+  latencyMs?: number;
+  error?: string;
+}
+
+interface ServicesStatusResponse {
+  summary: {
+    healthy: number;
+    unhealthy: number;
+    total: number;
+  };
+  services: ServiceStatus[];
+  timestamp: string;
+}
+
+/**
+ * Fetch running services from the API.
+ * Maps container names to service IDs for the admin sidebar.
+ */
+async function fetchRunningServices(): Promise<Set<string>> {
+  try {
+    const headers = await getAuthHeaders();
+    const response = await fetch('/api/_internal/services/status', { headers });
+    if (!response.ok) {
+      return new Set();
+    }
+    const data: ServicesStatusResponse = await response.json();
+
+    // Map container names to running status
+    const runningContainers = new Set(
+      data.services
+        .filter((s) => s.status === 'healthy' || s.status === 'unknown')
+        .map((s) => s.container)
+    );
+
+    return runningContainers;
+  } catch {
+    return new Set();
+  }
+}
+
+// Map container names to admin service IDs
+const containerToServiceId: Record<string, string> = {
+  studio: 'database',
+  traefik: 'gateway',
+  grafana: 'monitoring',
+  n8n: 'automation',
+  metabase: 'analytics',
+};
+
+/**
+ * Hook to get list of enabled admin services based on what's actually running.
+ *
+ * This combines:
+ * 1. Services that are always enabled (core infrastructure)
+ * 2. Services enabled via VITE_*_ENABLED env vars
+ * 3. Services detected as running via the services-status API
+ */
+export function useEnabledServices() {
+  const { data: runningContainers, isLoading } = useQuery({
+    queryKey: ['running-services'],
+    queryFn: fetchRunningServices,
+    staleTime: 30 * 1000, // 30 seconds
+    refetchInterval: 60 * 1000, // Refresh every minute
+  });
+
+  const enabledServices = adminServices.filter((service) => {
+    // Core services are always shown
+    if (service.alwaysEnabled) return true;
+
+    // Check env var first (for production deployments)
+    if (service.envFlag && import.meta.env[service.envFlag] === 'true') {
+      return true;
+    }
+
+    // In development, also check if the service is actually running
+    if (runningContainers) {
+      // Find the container name that maps to this service ID
+      const containerName = Object.entries(containerToServiceId).find(
+        ([, id]) => id === service.id
+      )?.[0];
+
+      if (containerName && runningContainers.has(containerName)) {
+        return true;
+      }
+    }
+
+    return false;
+  });
+
+  return {
+    services: enabledServices,
+    isLoading,
+    runningContainers: runningContainers || new Set(),
+  };
+}
+
+/**
+ * Check if a specific service is running
+ */
+export function useIsServiceRunning(serviceId: string) {
+  const { services, isLoading } = useEnabledServices();
+  return {
+    isRunning: services.some((s) => s.id === serviceId),
+    isLoading,
+  };
+}

package/carbon/src/client/hooks/useScrollProgress.ts

@@ -0,0 +1,56 @@
+import { type MotionValue, useScroll, useTransform } from 'framer-motion';
+import { useRef } from 'react';
+
+interface ScrollProgress {
+  scrollY: MotionValue<number>;
+  scrollYProgress: MotionValue<number>;
+  containerRef: React.RefObject<HTMLDivElement | null>;
+}
+
+/**
+ * Track overall page scroll progress
+ */
+export function useScrollProgress(): ScrollProgress {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const { scrollY, scrollYProgress } = useScroll({
+    target: containerRef,
+    offset: ['start start', 'end end'],
+  });
+
+  return { scrollY, scrollYProgress, containerRef };
+}
+
+interface SectionProgress {
+  scrollYProgress: MotionValue<number>;
+  centeredProgress: MotionValue<number>;
+  blur: MotionValue<number>;
+  scale: MotionValue<number>;
+  opacity: MotionValue<number>;
+}
+
+/**
+ * Track scroll progress for individual sections with depth-of-field transforms
+ * centeredProgress: -1 (above viewport) -> 0 (centered) -> 1 (below viewport)
+ */
+export function useSectionProgress(
+  sectionRef: React.RefObject<HTMLElement | null>
+): SectionProgress {
+  const { scrollYProgress } = useScroll({
+    target: sectionRef,
+    offset: ['start end', 'end start'],
+  });
+
+  // Transform to -1 (above viewport) -> 0 (centered) -> 1 (below viewport)
+  const centeredProgress = useTransform(scrollYProgress, [0, 0.5, 1], [-1, 0, 1]);
+
+  // Minimal blur effect - just a subtle hint of focus
+  const blur = useTransform(scrollYProgress, [0, 0.3, 0.5, 0.7, 1], [0, 0, 0, 0, 0]);
+
+  // No scale effect - keep sections stable
+  const scale = useTransform(scrollYProgress, [0, 0.5, 1], [1, 1, 1]);
+
+  // Subtle opacity for edge sections only
+  const opacity = useTransform(scrollYProgress, [0, 0.15, 0.5, 0.85, 1], [0.7, 1, 1, 1, 0.7]);
+
+  return { scrollYProgress, centeredProgress, blur, scale, opacity };
+}