@giouwur/biometric-sdk 1.0.0

package/templates/test-page.tsx

@@ -0,0 +1,1219 @@
+"use client";
+
+import { useState, useCallback, useEffect } from "react";
+import {
+  // Provider & Config
+  useBiometricConfig,
+
+  // Pre-built Modules
+  FingerEnrollModule,
+  FaceEnrollModule,
+  PalmEnrollModule,
+  IrisEnrollModule,
+  FingerRollEnrollModule,
+
+  // Stores
+  useEnrollmentStore,
+  useBiometricStore,
+  useUiStore,
+
+  // UI Components
+  Button,
+  Card,
+  Input,
+  Select,
+  QualityBadge,
+  StatusChip,
+  ProgressBar,
+  Modal,
+  Loader,
+  BiometricSlot,
+
+  // Utilities
+  getImageSrcForDisplay,
+  normalizeImageForStorage,
+
+  // Types
+  type BiometricConfig,
+  type BiometricItem,
+  type EnrollmentState,
+  type BiometricState,
+} from "@giouwur/biometric-sdk";
+
+import {
+  TbFingerprint,
+  TbFaceId,
+  TbHandStop,
+  TbEye,
+  TbScan,
+  TbCode,
+  TbApi,
+  TbPackage,
+  TbChevronDown,
+  TbChevronRight,
+  TbComponents,
+  TbPuzzle,
+  TbPalette,
+  TbDatabase,
+  TbBraces,
+  TbPhoto,
+  TbSettings,
+  TbSearch,
+  TbX,
+  TbTerminal2,
+  TbColorSwatch,
+} from "react-icons/tb";
+
+// ─── Constants & Types ───────────────────────────────────
+type SectionCategory = "basics" | "data" | "advanced" | "modules";
+
+interface SectionInfo {
+  id: string;
+  title: string;
+  category: SectionCategory;
+  icon: React.ElementType;
+  component: React.ReactNode;
+  keywords: string[];
+}
+
+// ─── Collapsible Section ─────────────────────────────────
+function Section({
+  title,
+  icon: Icon,
+  children,
+  isOpen,
+  onToggle,
+}: {
+  title: string;
+  icon: React.ElementType;
+  children: React.ReactNode;
+  isOpen: boolean;
+  onToggle: () => void;
+}) {
+  return (
+    <section className="bg-card border border-border/50 rounded-xl shadow-sm overflow-hidden animate-in fade-in slide-in-from-bottom-2 duration-300">
+      <button
+        onClick={onToggle}
+        className="w-full flex items-center justify-between px-6 py-4 hover:bg-secondary/30 transition-colors"
+      >
+        <div className="flex items-center gap-3">
+          <div className="p-2 rounded-lg bg-primary/10 text-primary">
+            <Icon size={20} />
+          </div>
+          <h2 className="text-lg font-semibold text-foreground">{title}</h2>
+        </div>
+        {isOpen ? <TbChevronDown size={20} /> : <TbChevronRight size={20} />}
+      </button>
+      {isOpen && (
+        <div className="px-6 pb-6 border-t border-border/30 pt-4">
+          {children}
+        </div>
+      )}
+    </section>
+  );
+}
+
+// ─── Code Block ──────────────────────────────────────────
+function CodeBlock({ code, title }: { code: string; title?: string }) {
+  return (
+    <div className="rounded-lg bg-[#0d1117] border border-white/10 overflow-hidden">
+      {title && (
+        <div className="px-4 py-2 bg-white/5 border-b border-white/10 text-xs font-mono text-white/50">
+          {title}
+        </div>
+      )}
+      <pre className="p-4 text-sm font-mono text-green-400 overflow-x-auto whitespace-pre-wrap">
+        {code}
+      </pre>
+    </div>
+  );
+}
+
+// ─── 1. Provider Example ──────────────────────────────────
+function ProviderExample() {
+  const config = useBiometricConfig();
+  return (
+    <div className="space-y-4">
+      <p className="text-sm text-foreground/60">
+        Tu app debe estar envuelta con{" "}
+        <code className="px-1.5 py-0.5 bg-secondary rounded text-xs font-mono">
+          {"<BiometricProvider>"}
+        </code>.
+        Aquí está la configuración activa:
+      </p>
+      <div className="grid grid-cols-3 gap-3">
+        {[
+          { label: "WebSocket", value: config.wsUrl },
+          { label: "API Base", value: config.apiBaseUrl || "—" },
+          { label: "Device ID", value: config.deviceId || "—" },
+        ].map(({ label, value }) => (
+          <div key={label} className="p-3 bg-secondary/30 rounded-lg border border-border/30">
+            <p className="text-[10px] font-bold text-foreground/40 uppercase tracking-wider">{label}</p>
+            <p className="text-sm font-mono text-primary truncate">{value}</p>
+          </div>
+        ))}
+      </div>
+      <CodeBlock
+        title="layout.tsx — Ejemplo de configuración"
+        code={`import { BiometricProvider } from '@intell/biometric-sdk';
+
+export default function Layout({ children }) {
+  return (
+    <BiometricProvider config={{
+      wsUrl: "ws://127.0.0.1:5000/biometric",
+      apiBaseUrl: "http://localhost:8080/api/v1",
+      deviceId: "scanner_01"
+    }}>
+      {children}
+    </BiometricProvider>
+  );
+}`}
+      />
+    </div>
+  );
+}
+
+// ─── 2. UI Components Showcase ───────────────────────────
+function UIComponentsShowcase() {
+  const [modalOpen, setModalOpen] = useState(false);
+  const [selectValue, setSelectValue] = useState("opt1");
+  const [inputValue, setInputValue] = useState("");
+
+  return (
+    <div className="space-y-8">
+      {/* Buttons */}
+      <div>
+        <h3 className="text-sm font-bold text-foreground/70 mb-3 uppercase tracking-wider">
+          Button — 6 variantes × 3 tamaños
+        </h3>
+        <div className="flex flex-wrap gap-3 mb-3">
+          <Button variant="primary">Primary</Button>
+          <Button variant="secondary">Secondary</Button>
+          <Button variant="success">Success</Button>
+          <Button variant="danger">Danger</Button>
+          <Button variant="warning">Warning</Button>
+          <Button variant="ghost">Ghost</Button>
+        </div>
+        <div className="flex flex-wrap items-center gap-3">
+          <Button size="sm">Small</Button>
+          <Button size="md">Medium</Button>
+          <Button size="lg">Large</Button>
+          <Button isLoading>Loading...</Button>
+          <Button disabled>Disabled</Button>
+          <Button icon={<TbFingerprint />}>Con Icono</Button>
+        </div>
+      </div>
+
+      {/* StatusChip */}
+      <div>
+        <h3 className="text-sm font-bold text-foreground/70 mb-3 uppercase tracking-wider">
+          StatusChip — 5 estados
+        </h3>
+        <div className="flex flex-wrap gap-3">
+          <StatusChip status="success" label="Conectado" />
+          <StatusChip status="warning" label="Advertencia" />
+          <StatusChip status="danger" label="Error" />
+          <StatusChip status="info" label="Información" />
+          <StatusChip status="neutral" label="Neutral" />
+          <StatusChip status="success" label="Cargando..." isLoading />
+          <StatusChip status="info" label="Mini" size="sm" />
+        </div>
+      </div>
+
+      {/* QualityBadge */}
+      <div>
+        <h3 className="text-sm font-bold text-foreground/70 mb-3 uppercase tracking-wider">
+          QualityBadge — Calidad dinámica
+        </h3>
+        <div className="flex gap-4 items-center">
+          <QualityBadge quality={95} />
+          <QualityBadge quality={72} />
+          <QualityBadge quality={35} />
+          <span className="text-xs text-foreground/40">≥80 Verde • ≥50 Amarillo • &lt;50 Rojo</span>
+        </div>
+      </div>
+
+      {/* ProgressBar */}
+      <div>
+        <h3 className="text-sm font-bold text-foreground/70 mb-3 uppercase tracking-wider">
+          ProgressBar
+        </h3>
+        <ProgressBar current={7} total={10} label="Biométricos capturados" />
+      </div>
+
+      {/* Input */}
+      <div>
+        <h3 className="text-sm font-bold text-foreground/70 mb-3 uppercase tracking-wider">
+          Input
+        </h3>
+        <div className="max-w-md">
+          <Input
+            label="Nombre del solicitante"
+            placeholder="Ej. Juan Pérez"
+            icon={<TbFingerprint />}
+            value={inputValue}
+            onChange={(e) => setInputValue(e.target.value)}
+          />
+        </div>
+      </div>
+
+      {/* Select */}
+      <div>
+        <h3 className="text-sm font-bold text-foreground/70 mb-3 uppercase tracking-wider">
+          Select
+        </h3>
+        <div className="max-w-md">
+          <Select
+            value={selectValue}
+            onChange={setSelectValue}
+            options={[
+              { value: "opt1", label: "Huella Plana", icon: <TbFingerprint /> },
+              { value: "opt2", label: "Huella Rolada", icon: <TbScan /> },
+              { value: "opt3", label: "Rostro", icon: <TbFaceId /> },
+            ]}
+          />
+        </div>
+      </div>
+
+      {/* Card */}
+      <div>
+        <h3 className="text-sm font-bold text-foreground/70 mb-3 uppercase tracking-wider">
+          Card
+        </h3>
+        <div className="grid grid-cols-3 gap-3">
+          <Card className="p-4">
+            <p className="text-sm font-bold">Default Card</p>
+            <p className="text-xs text-foreground/50">Contenido</p>
+          </Card>
+          <Card variant="glass" className="p-4">
+            <p className="text-sm font-bold">Glass Card</p>
+            <p className="text-xs text-foreground/50">Translúcida</p>
+          </Card>
+          <Card variant="outlined" className="p-4">
+            <p className="text-sm font-bold">Outlined Card</p>
+            <p className="text-xs text-foreground/50">Solo borde</p>
+          </Card>
+        </div>
+      </div>
+
+      {/* Loader */}
+      <div>
+        <h3 className="text-sm font-bold text-foreground/70 mb-3 uppercase tracking-wider">
+          Loader
+        </h3>
+        <div className="flex gap-6 items-center">
+          <Loader size={16} />
+          <Loader size={24} text="Cargando..." />
+          <Loader size={32} />
+        </div>
+      </div>
+
+      {/* Modal */}
+      <div>
+        <h3 className="text-sm font-bold text-foreground/70 mb-3 uppercase tracking-wider">
+          Modal
+        </h3>
+        <Button onClick={() => setModalOpen(true)}>Abrir Modal</Button>
+        <Modal isOpen={modalOpen} onClose={() => setModalOpen(false)} title="Modal de Ejemplo">
+          <p className="text-foreground/70 mb-4">Este es un modal reutilizable del SDK.</p>
+          <div className="flex gap-3 justify-end">
+            <Button variant="ghost" onClick={() => setModalOpen(false)}>Cancelar</Button>
+            <Button onClick={() => setModalOpen(false)}>Confirmar</Button>
+          </div>
+        </Modal>
+      </div>
+    </div>
+  );
+}
+
+// ─── 3. Style Customization ──────────────────────────────
+function StyleCustomizationExample() {
+  return (
+    <div className="space-y-4">
+      <p className="text-sm text-foreground/60">
+        Todos los componentes aceptan <code className="px-1.5 py-0.5 bg-secondary rounded text-xs font-mono">className</code>.
+        Como usan Tailwind, puedes extender/sobreescribir estilos:
+      </p>
+      <div className="grid grid-cols-2 gap-4">
+        <div>
+          <p className="text-xs font-bold text-foreground/40 mb-2">Default</p>
+          <Button>Default Button</Button>
+        </div>
+        <div>
+          <p className="text-xs font-bold text-foreground/40 mb-2">Custom className</p>
+          <Button className="!bg-gradient-to-r !from-pink-500 !to-violet-500 !rounded-full !px-8">
+            Custom Style
+          </Button>
+        </div>
+      </div>
+      <div className="grid grid-cols-2 gap-4">
+        <div>
+          <p className="text-xs font-bold text-foreground/40 mb-2">Default Card</p>
+          <Card className="p-4">
+            <p className="text-sm">Card normal</p>
+          </Card>
+        </div>
+        <div>
+          <p className="text-xs font-bold text-foreground/40 mb-2">Custom Card</p>
+          <Card className="p-4 !bg-gradient-to-br !from-emerald-500/20 !to-teal-500/20 !border-emerald-500/30">
+            <p className="text-sm text-emerald-400">Card personalizada ✨</p>
+          </Card>
+        </div>
+      </div>
+      <CodeBlock
+        title="Personalizando estilos"
+        code={`// Sobreescribir con className + !important de Tailwind
+<Button className="!bg-gradient-to-r !from-pink-500 !to-violet-500 !rounded-full">
+  Custom Button
+</Button>
+
+// Card personalizada 
+<Card className="!bg-emerald-500/20 !border-emerald-500/30">
+  <p className="text-emerald-400">Themed Card</p>
+</Card>
+
+// Módulo con className
+<FingerEnrollModule className="max-w-3xl mx-auto" />`}
+      />
+    </div>
+  );
+}
+
+// ─── 4. Store & Data Access ──────────────────────────────
+function StoreAccessExample() {
+  const enrollment = useEnrollmentStore();
+  const biometric = useBiometricStore();
+  const ui = useUiStore();
+
+  const fingerCount = Object.keys(enrollment.fingerprints).length;
+  const rolledCount = Object.keys(enrollment.rolledFingerprints).length;
+  const palmCount = Object.keys(enrollment.palms).length;
+  const faceCount = enrollment.faces.length;
+  const irisCount = [enrollment.irises.left, enrollment.irises.right].filter(Boolean).length;
+  const missingCount = Object.keys(enrollment.missingFingers).length;
+
+  return (
+    <div className="space-y-4">
+      <p className="text-sm text-foreground/60">
+        Acceso directo a <strong>todo el estado</strong> del SDK via stores de Zustand:
+      </p>
+
+      {/* Live State Dashboard */}
+      <div className="grid grid-cols-2 md:grid-cols-4 gap-3">
+        {[
+          { label: "Huellas Planas", value: fingerCount, icon: <TbFingerprint />, color: "text-blue-400" },
+          { label: "Huellas Roladas", value: rolledCount, icon: <TbScan />, color: "text-purple-400" },
+          { label: "Palmas", value: palmCount, icon: <TbHandStop />, color: "text-orange-400" },
+          { label: "Rostros", value: faceCount, icon: <TbFaceId />, color: "text-pink-400" },
+          { label: "Iris", value: irisCount, icon: <TbEye />, color: "text-cyan-400" },
+          { label: "Faltantes", value: missingCount, icon: <TbFingerprint />, color: "text-red-400" },
+          { label: "External ID", value: enrollment.externalId || "—", icon: <TbDatabase />, color: "text-green-400" },
+          { label: "Modo", value: enrollment.isUpdateMode ? "Update" : "New", icon: <TbSettings />, color: "text-yellow-400" },
+        ].map(({ label, value, icon, color }) => (
+          <div key={label} className="p-3 bg-secondary/30 rounded-lg border border-border/30 flex items-center gap-3">
+            <div className={`${color}`}>{icon}</div>
+            <div>
+              <p className="text-[10px] text-foreground/40 uppercase tracking-wider">{label}</p>
+              <p className="text-sm font-bold text-foreground">{String(value)}</p>
+            </div>
+          </div>
+        ))}
+      </div>
+
+      {/* Device Status */}
+      <div className="flex items-center gap-4">
+        <StatusChip
+          status={biometric.isConnected ? "success" : "danger"}
+          label={biometric.isConnected ? "WebSocket Online" : "WebSocket Offline"}
+        />
+        <span className="text-xs text-foreground/40">
+          Mensajes UI: {ui.messages.length}
+        </span>
+      </div>
+
+      <CodeBlock
+        title="Acceso a stores"
+        code={`import { useEnrollmentStore, useBiometricStore, useUiStore } from '@intell/biometric-sdk';
+import type { BiometricItem, EnrollmentState, BiometricState } from '@intell/biometric-sdk';
+
+// Leer estado  
+const { fingerprints, faces, irises } = useEnrollmentStore();
+const { isConnected, deviceStatus } = useBiometricStore();
+
+// Tipar custom components
+const myFingers: Record<string, BiometricItem> = fingerprints;
+
+// Suscripción selectiva (Zustand selector)
+const count = useEnrollmentStore(s => Object.keys(s.fingerprints).length);
+
+// Acceso fuera de React
+const state = useEnrollmentStore.getState();
+const payload = state.buildEnrollmentRequest();`}
+      />
+    </div>
+  );
+}
+
+// ─── 5. Custom Slot Grid ─────────────────────────────────
+function CustomSlotGrid() {
+  const { fingerprints, addFingerprint, removeFingerprint, addMissingFinger, removeMissingFinger, missingFingers } =
+    useEnrollmentStore();
+  const { sendMessage, registerHandler, isConnected } = useBiometricStore();
+
+  const positions = [
+    { key: "RIGHT_THUMB", label: "Pulgar D." },
+    { key: "RIGHT_INDEX", label: "Índice D." },
+    { key: "RIGHT_MIDDLE", label: "Medio D." },
+    { key: "RIGHT_RING", label: "Anular D." },
+    { key: "RIGHT_LITTLE", label: "Meñique D." },
+  ];
+
+  const handleCapture = useCallback(
+    (pos: string) => {
+      if (!isConnected) return;
+      registerHandler("fingerprint_captured", (msg: any) => {
+        addFingerprint(pos, msg.image, msg.quality);
+      });
+      sendMessage({ messageType: "capture_fingerprint", position: pos });
+    },
+    [isConnected, registerHandler, sendMessage, addFingerprint]
+  );
+
+  return (
+    <div className="space-y-4">
+      <p className="text-sm text-foreground/60">
+        Grid custom usando <code className="px-1.5 py-0.5 bg-secondary rounded text-xs font-mono">BiometricSlot</code> + stores.
+        Tú decides el layout, posiciones y callbacks:
+      </p>
+      <div className="grid grid-cols-5 gap-3">
+        {positions.map(({ key, label }) => {
+          const fp = fingerprints[key];
+          const missing = missingFingers[key];
+          return (
+            <BiometricSlot
+              key={key}
+              title={label}
+              position={key}
+              iconType="finger"
+              status={fp ? "captured" : "pending"}
+              quality={fp?.quality}
+              imageUrl={fp ? getImageSrcForDisplay(fp.image) : null}
+              onCapture={() => handleCapture(key)}
+              onDelete={() => removeFingerprint(key)}
+              onRequestMissing={() => addMissingFinger(key, "Amputación")}
+              onRestore={() => removeMissingFinger(key)}
+              missingReason={missing}
+            />
+          );
+        })}
+      </div>
+      <CodeBlock
+        title="Código del grid custom"
+        code={`import { BiometricSlot, useEnrollmentStore, useBiometricStore, getImageSrcForDisplay } from '@intell/biometric-sdk';
+
+const positions = ['RIGHT_THUMB', 'RIGHT_INDEX', 'RIGHT_MIDDLE'];
+
+function MyGrid() {
+  const { fingerprints, addFingerprint, removeFingerprint } = useEnrollmentStore();
+  const { sendMessage, registerHandler } = useBiometricStore();
+
+  return (
+    <div className="grid grid-cols-5 gap-3">
+      {positions.map(pos => {
+        const fp = fingerprints[pos];
+        return (
+          <BiometricSlot
+            key={pos}
+            title={pos}
+            position={pos}
+            iconType="finger"
+            status={fp ? 'captured' : 'pending'}
+            quality={fp?.quality}
+            imageUrl={fp ? getImageSrcForDisplay(fp.image) : null}
+            onCapture={() => { /* tu lógica */ }}
+            onDelete={() => removeFingerprint(pos)}
+          />
+        );
+      })}
+    </div>
+  );
+}`}
+      />
+    </div>
+  );
+}
+
+// ─── 6. Custom Capture Modal ─────────────────────────────
+function CustomCaptureModalExample() {
+  return (
+    <div className="space-y-4">
+      <p className="text-sm text-foreground/60">
+        Crea tu propio flujo de captura con las primitivas del SDK:
+      </p>
+      <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+        <Card className="p-4 space-y-2">
+          <h4 className="font-bold text-sm text-primary">sendMessage()</h4>
+          <p className="text-xs text-foreground/60">Envía comandos al dispositivo vía WebSocket</p>
+          <CodeBlock code={`sendMessage({
+  messageType: 'capture_fingerprint',
+  position: 'RIGHT_INDEX'
+});`} />
+        </Card>
+        <Card className="p-4 space-y-2">
+          <h4 className="font-bold text-sm text-primary">registerHandler()</h4>
+          <p className="text-xs text-foreground/60">Recibe respuestas del dispositivo</p>
+          <CodeBlock code={`registerHandler('fingerprint_captured',
+  (msg) => {
+    // msg.image = base64
+    // msg.quality = 0-100
+    addFingerprint(pos, msg.image,
+      msg.quality);
+  }
+);`} />
+        </Card>
+        <Card className="p-4 space-y-2">
+          <h4 className="font-bold text-sm text-primary">Store Methods</h4>
+          <p className="text-xs text-foreground/60">Agregar/remover datos biométricos</p>
+          <CodeBlock code={`// Huellas
+addFingerprint(pos, image, quality)
+removeFingerprint(pos)
+addMissingFinger(pos, reason)
+
+// Rostros
+setFaces([{image, quality}])
+removeFace(index)
+
+// Iris
+setIrises(right, left)
+removeIris('left')
+
+// Palmas
+addPalm(pos, image, quality)`} />
+        </Card>
+      </div>
+      <CodeBlock
+        title="Tu propio modal de captura facial"
+        code={`import { Modal, Button, useBiometricStore, useEnrollmentStore } from '@intell/biometric-sdk';
+
+function MyFaceCapture({ isOpen, onClose }) {
+  const { sendMessage, registerHandler, unregisterHandler } = useBiometricStore();
+  const { setFaces } = useEnrollmentStore();
+  const [preview, setPreview] = useState(null);
+
+  useEffect(() => {
+    registerHandler('face_captured', (msg) => setPreview(msg.image));
+    return () => unregisterHandler('face_captured');
+  }, []);
+
+  return (
+    <Modal isOpen={isOpen} onClose={onClose} title="Mi Captura">
+      {preview ? <img src={preview} /> : <Loader text="Esperando..." />}
+      <Button onClick={() => sendMessage({ messageType: 'start_face' })}>Capturar</Button>
+      <Button onClick={() => { setFaces([{ image: preview, quality: 95 }]); onClose(); }}>
+        Confirmar
+      </Button>
+    </Modal>
+  );
+}`}
+      />
+    </div>
+  );
+}
+
+// ─── 7. Types & Extensions ───────────────────────────────
+function TypesExample() {
+  return (
+    <div className="space-y-4">
+      <p className="text-sm text-foreground/60">
+        Todos los tipos del SDK están exportados para tipar tus custom components:
+      </p>
+      <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+        <CodeBlock
+          title="Tipos de Store disponibles"
+          code={`import type {
+  // Estado de enrolamiento
+  BiometricItem,        // { image, quality, impressionType? }
+  EnrollmentState,      // Estado completo del enrollment
+  OriginalSnapshot,     // Snapshot para dirty tracking
+
+  // Estado del dispositivo
+  BiometricState,       // WebSocket + device status
+  DeviceStatus,         // { fingerprintDevices, irisDeviceOpen }
+  SocketMessage,        // { messageType, ...data }
+  MessageHandler,       // (message) => void
+
+  // UI state
+  UiState,              // { messages, isConsoleOpen, ... }
+} from '@intell/biometric-sdk';`}
+        />
+        <CodeBlock
+          title="Tipos de Componentes"
+          code={`import type {
+  // Props de componentes
+  ButtonProps,          // extends HTMLButtonAttributes
+  CardProps,            // variant, padding, rounded, ...
+  InputProps,           // extends HTMLInputAttributes
+  ModalProps,           // isOpen, onClose, title, ...
+  BiometricSlotProps,   // title, status, quality, ...
+  BiometricConfig,      // wsUrl, apiBaseUrl, deviceId
+
+  // ABIS Protocol
+  EnrollApplicantRequest,
+  FingerprintPosition,
+  FingerprintImpressionType,
+  IrisPosition,
+  EnrollAction,
+} from '@intell/biometric-sdk';`}
+        />
+      </div>
+      <CodeBlock
+        title="Ejemplo: Extender un componente del SDK"
+        code={`import { Button, type ButtonProps } from '@intell/biometric-sdk';
+
+// Componente que extiende Button con funcionalidad extra
+interface MyButtonProps extends ButtonProps {
+  tooltip?: string;
+  analytics?: string;
+}
+
+function MyButton({ tooltip, analytics, onClick, ...rest }: MyButtonProps) {
+  const handleClick = (e) => {
+    if (analytics) trackEvent(analytics);
+    onClick?.(e);
+  };
+  return (
+    <div title={tooltip}>
+      <Button onClick={handleClick} {...rest} />
+    </div>
+  );
+}`}
+      />
+    </div>
+  );
+}
+
+// ─── 8. API Integration ──────────────────────────────────
+function ApiCallExample() {
+  const config = useBiometricConfig();
+  const { buildEnrollmentRequest, loadApplicantData, setDemographics } =
+    useEnrollmentStore();
+  const [response, setResponse] = useState("");
+
+  const handleBuildPayload = () => {
+    const payload = buildEnrollmentRequest();
+    setResponse(JSON.stringify(payload, null, 2));
+  };
+
+  const handleSimulateLoad = async () => {
+    setDemographics("EXT-001", "Juan Pérez");
+    setResponse(
+      `✅ Datos cargados.\n\nEn producción:\nconst res = await fetch('${config.apiBaseUrl}/applicant/EXT-001');\nconst data = await res.json();\nawait loadApplicantData(data);`
+    );
+  };
+
+  const handleSimulateEnroll = () => {
+    const payload = buildEnrollmentRequest();
+    setResponse(
+      `📤 En producción:\n\nawait fetch('${config.apiBaseUrl}/biometric/enrollment', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify(payload)\n});\n\n${JSON.stringify(payload, null, 2).slice(0, 400)}...`
+    );
+  };
+
+  return (
+    <div className="space-y-4">
+      <p className="text-sm text-foreground/60">
+        El SDK <strong>NO</strong> hace llamadas API. Tu front es quien se comunica con el backend.
+      </p>
+      <CodeBlock
+        title="Flujo completo"
+        code={`const { apiBaseUrl } = useBiometricConfig();
+
+// 1. Tu front busca datos existentes
+const res = await fetch(\`\${apiBaseUrl}/applicant/\${id}\`);
+const data = await res.json();
+
+// 2. El SDK mapea los datos al estado interno
+await useEnrollmentStore.getState().loadApplicantData(data);
+
+// 3. El usuario captura biometría con los módulos...
+
+// 4. El SDK arma el payload
+const payload = useEnrollmentStore.getState().buildEnrollmentRequest();
+
+// 5. Tu front envía
+await fetch(\`\${apiBaseUrl}/biometric/enrollment\`, {
+  method: 'POST', body: JSON.stringify(payload)
+});`}
+      />
+      <div className="flex gap-3 flex-wrap">
+        <Button onClick={handleSimulateLoad} variant="secondary" size="sm">loadApplicantData()</Button>
+        <Button onClick={handleBuildPayload} variant="secondary" size="sm">buildEnrollmentRequest()</Button>
+        <Button onClick={handleSimulateEnroll} variant="primary" size="sm">Simular Envío</Button>
+      </div>
+      {response && (
+        <pre className="p-4 bg-[#0d1117] rounded-lg text-xs font-mono text-green-400 max-h-60 overflow-auto border border-white/10 whitespace-pre-wrap">
+          {response}
+        </pre>
+      )}
+    </div>
+  );
+}
+
+// ─── 9. Utilities ────────────────────────────────────────
+function UtilitiesExample() {
+  return (
+    <div className="space-y-4">
+      <p className="text-sm text-foreground/60">
+        Utilidades de imagen exportadas para manipular datos biométricos:
+      </p>
+      <CodeBlock
+        title="Utilidades de imagen disponibles"
+        code={`import {
+  normalizeImageForStorage,  // Limpia prefijos data:image/... para storage
+  getImageSrcForDisplay,     // Agrega prefijo data:image/... para <img>
+  isRemoteImage,             // Detecta si es URL HTTP(s)
+  downloadImageAsBase64,     // Descarga imagen remota a base64
+  canvasToBase64,            // Canvas → base64
+  base64toBlob,              // base64 → Blob (para FormData)
+  detectImageFormat,         // Detecta formato (png, jpg, bmp, wsq)
+  isValidBase64,             // Valida string base64
+} from '@intell/biometric-sdk';
+
+// Ejemplo: Convertir captura a Blob para subir por FormData
+const blob = base64toBlob(fingerprint.image);
+const formData = new FormData();
+formData.append('image', blob, 'fingerprint.png');
+
+// Ejemplo: Mostrar imagen en <img>
+const src = getImageSrcForDisplay(fingerprint.image);
+return <img src={src} alt="Huella" />;`}
+      />
+    </div>
+  );
+}
+
+// ─── 10. Advanced: Full Custom Components ─────────────────
+function FullCustomComponentExample() {
+  const { fingerprints, removeFingerprint } = useEnrollmentStore();
+  const { isConnected, sendMessage } = useBiometricStore();
+
+  const handleManualCapture = (pos: string) => {
+    sendMessage({ messageType: "capture_fingerprint", position: pos });
+  };
+
+  return (
+    <div className="space-y-6">
+      <div className="p-4 bg-amber-500/10 border border-amber-500/20 rounded-lg">
+        <p className="text-xs text-amber-500 font-bold uppercase tracking-widest mb-1">Concepto Avanzado</p>
+        <p className="text-sm text-foreground/80">
+          A veces no quieres usar <code className="text-xs font-mono bg-amber-500/10 px-1 rounded">BiometricSlot</code>.
+          Aquí tienes un ejemplo de cómo construir tu propio UI interactivo directamente sobre los stores.
+        </p>
+      </div>
+
+      <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+        {/* Concept 1: Minimalist Row Slot */}
+        <div className="space-y-3">
+          <h4 className="text-xs font-bold uppercase text-foreground/40">1. Minimalist Row Slot</h4>
+          <div className="p-3 bg-secondary/20 rounded-lg border border-border/30 flex items-center justify-between hover:border-primary/50 transition-all group">
+            <div className="flex items-center gap-3">
+              <div className={`w-10 h-10 rounded-full flex items-center justify-center ${fingerprints['RIGHT_THUMB'] ? 'bg-success/20 text-success' : 'bg-foreground/5 text-foreground/20'}`}>
+                <TbFingerprint size={24} />
+              </div>
+              <div>
+                <p className="text-sm font-bold">Pulgar Derecho</p>
+                <p className="text-[10px] text-foreground/40 uppercase tracking-tighter">
+                  {fingerprints['RIGHT_THUMB'] ? `Calidad: ${fingerprints['RIGHT_THUMB'].quality}%` : 'Pendiente de captura'}
+                </p>
+              </div>
+            </div>
+            <div className="flex items-center gap-2">
+              {fingerprints['RIGHT_THUMB'] ? (
+                <Button variant="ghost" size="sm" onClick={() => removeFingerprint('RIGHT_THUMB')}>
+                  Descartar
+                </Button>
+              ) : (
+                <Button variant="primary" size="sm" onClick={() => handleManualCapture('RIGHT_THUMB')} disabled={!isConnected}>
+                  Capturar
+                </Button>
+              )}
+            </div>
+          </div>
+          <CodeBlock title="Código: Slot minimalista custom" code={`function MyMinimalSlot({ pos }) {
+  const fp = useEnrollmentStore(s => s.fingerprints[pos]);
+  const capture = () => sendMessage({ 
+    messageType: 'capture_fingerprint', position: pos 
+  });
+  
+  return (
+    <div className="flex justify-between items-center">
+      <span>{pos}</span>
+      <button onClick={capture}>{fp ? 'Repetir' : 'Capturar'}</button>
+    </div>
+  );
+}`} />
+        </div>
+
+        {/* Concept 2: Full Custom Modal Overlay */}
+        <div className="space-y-3">
+          <h4 className="text-xs font-bold uppercase text-foreground/40">2. Custom Modal Overlay</h4>
+          <div className="aspect-video bg-black rounded-lg relative overflow-hidden flex items-center justify-center border border-white/10 group">
+            {/* Camera Simulation */}
+            <div className="absolute inset-0 bg-blue-500/5 flex items-center justify-center">
+               <TbFaceId size={60} className="text-white/10 animate-pulse" />
+            </div>
+            
+            {/* Custom UI Overlays */}
+            <div className="absolute top-4 left-4">
+              <div className="px-2 py-1 bg-black/60 backdrop-blur-md rounded border border-white/20 text-[10px] font-bold text-white uppercase tracking-widest">
+                REC ● LIVE
+              </div>
+            </div>
+            
+            <div className="absolute bottom-4 inset-x-4 flex justify-between items-end">
+               <div className="p-2 bg-black/40 rounded text-[10px] text-white/60 font-mono">
+                 30 FPS <br/> ISO 400
+               </div>
+               <button className="w-12 h-12 rounded-full bg-white border-4 border-white/20 shadow-xl active:scale-95 transition-all" />
+               <div className="p-2 bg-black/40 rounded text-[10px] text-white/60 text-right font-mono">
+                 85% <br/> MATCH
+               </div>
+            </div>
+
+            {/* Scanning line effect */}
+            <div className="absolute top-0 inset-x-0 h-1 bg-primary/40 shadow-[0_0_15px_rgba(var(--primary),0.8)] animate-scan-line" />
+          </div>
+          <p className="text-[10px] text-foreground/40 italic">Muestra de cómo puedes crear tu propio visor de captura con overlays personalizados.</p>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// ─── 10. Theming & Custom CSS Variables ───────────────────
+function ThemingExample() {
+  return (
+    <div className="space-y-4">
+      <p className="text-sm text-foreground/60">
+        El SDK usa variables CSS nativas para sus colores. Puedes cambiarlas globalmente o solo para un módulo:
+      </p>
+      <div className="p-5 bg-[#0d1117] rounded-xl border border-white/10">
+        <h4 className="flex items-center gap-2 text-xs font-bold text-white/60 uppercase mb-4">
+          <TbColorSwatch className="text-primary" /> Variables CSS Disponibles
+        </h4>
+        <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+          <div className="space-y-4">
+            <div className="space-y-1">
+              <p className="text-[10px] text-white/30 font-mono">--primary</p>
+              <div className="flex gap-2 items-center">
+                <div className="w-4 h-4 rounded bg-primary" />
+                <span className="text-xs text-white/70">Color principal / acción</span>
+              </div>
+            </div>
+            <div className="space-y-1">
+              <p className="text-[10px] text-white/30 font-mono">--success</p>
+              <div className="flex gap-2 items-center">
+                <div className="w-4 h-4 rounded bg-success" />
+                <span className="text-xs text-white/70">Calidad alta / éxito</span>
+              </div>
+            </div>
+            <div className="space-y-1">
+              <p className="text-[10px] text-white/30 font-mono">--danger</p>
+              <div className="flex gap-2 items-center">
+                <div className="w-4 h-4 rounded bg-danger" />
+                <span className="text-xs text-white/70">Error / Omisión</span>
+              </div>
+            </div>
+          </div>
+          <div className="space-y-4">
+            <div className="space-y-1">
+              <p className="text-[10px] text-white/30 font-mono">--background / --foreground</p>
+              <span className="text-xs text-white/70">Colores base (textos y fondos)</span>
+            </div>
+            <div className="space-y-1">
+              <p className="text-[10px] text-white/30 font-mono">--card / --border</p>
+              <span className="text-xs text-white/70">Superficies y divisiones</span>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <CodeBlock title="Inyectando tu tema" code={`/* En tu globals.css o un style tag */
+.my-custom-theme {
+  --primary: 219 255 0; /* Un verde vibrante */
+  --primary-foreground: 0 0 0;
+  --success: 34 197 94;
+}
+
+// Aplicar solo a un módulo
+<FingerEnrollModule className="my-custom-theme" />`} />
+    </div>
+  );
+}
+
+// ─── Main Test Page ──────────────────────────────────────
+export default function TestSDKPage() {
+  const [mounted, setMounted] = useState(false);
+  const [search, setSearch] = useState("");
+  const [openSections, setOpenSections] = useState<Record<string, boolean>>({
+    "intro": true,
+  });
+
+  const config = useBiometricConfig();
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  const sections: SectionInfo[] = [
+    {
+      id: "config",
+      title: "1. Configuración (Provider)",
+      category: "basics",
+      icon: TbSettings,
+      component: <ProviderExample />,
+      keywords: ["config", "provider", "wsurl", "apibaseurl", "setup", "init"],
+    },
+    {
+      id: "ui",
+      title: "2. Componentes UI",
+      category: "basics",
+      icon: TbComponents,
+      component: <UIComponentsShowcase />,
+      keywords: ["button", "card", "input", "select", "badge", "chip", "loader", "modal", "ui"],
+    },
+    {
+      id: "styling",
+      title: "3. Personalización de Estilos",
+      category: "basics",
+      icon: TbPalette,
+      component: <StyleCustomizationExample />,
+      keywords: ["style", "css", "tailwind", "classname", "theme", "colors"],
+    },
+    {
+      id: "theming",
+      title: "4. Tematización (CSS Vars)",
+      category: "basics",
+      icon: TbColorSwatch,
+      component: <ThemingExample />,
+      keywords: ["theme", "variables", "css", "colors", "primary", "branding"],
+    },
+    {
+      id: "data",
+      title: "5. Acceso a Datos y Stores",
+      category: "data",
+      icon: TbDatabase,
+      component: <StoreAccessExample />,
+      keywords: ["store", "data", "zustand", "enrollment", "biometric", "state"],
+    },
+    {
+       id: "api",
+       title: "6. Integración API",
+       category: "data",
+       icon: TbApi,
+       component: <ApiCallExample />,
+       keywords: ["api", "fetch", "enrollment", "payload", "loadapplicantdata", "backend"],
+    },
+    {
+      id: "utils",
+      title: "7. Utilidades de Imagen",
+      category: "data",
+      icon: TbPhoto,
+      component: <UtilitiesExample />,
+      keywords: ["image", "base64", "photo", "convert", "blob", "src", "utility"],
+    },
+    {
+      id: "custom-grid",
+      title: "8. Grid Custom de Slots",
+      category: "advanced",
+      icon: TbFingerprint,
+      component: <CustomSlotGrid />,
+      keywords: ["custom", "slot", "grid", "position", "finger", "build"],
+    },
+    {
+      id: "advanced-custom",
+      title: "9. Componentes 100% Custom",
+      category: "advanced",
+      icon: TbTerminal2,
+      component: <FullCustomComponentExample />,
+      keywords: ["advanced", "scratch", "manual", "custom", "example", "architecture"],
+    },
+    {
+      id: "capture-modal",
+      title: "10. Modal de Captura Custom",
+      category: "advanced",
+      icon: TbPuzzle,
+      component: <CustomCaptureModalExample />,
+      keywords: ["modal", "capture", "websocket", "sendmessage", "registerhandler", "custom"],
+    },
+    {
+      id: "types",
+      title: "11. Tipos y Extensiones",
+      category: "advanced",
+      icon: TbBraces,
+      component: <TypesExample />,
+      keywords: ["types", "typescript", "interfaces", "props", "extending"],
+    },
+    {
+      id: "mod-finger",
+      title: "12. Módulo: Huellas Planas",
+      category: "modules",
+      icon: TbFingerprint,
+      component: <FingerEnrollModule />,
+      keywords: ["finger", "fingerprint", "huella", "plana", "module"],
+    },
+    {
+      id: "mod-rolled",
+      title: "13. Módulo: Huellas Roladas",
+      category: "modules",
+      icon: TbScan,
+      component: <FingerRollEnrollModule />,
+      keywords: ["rolled", "fingerprint", "huella", "rolada", "module"],
+    },
+    {
+      id: "mod-palm",
+      title: "14. Módulo: Palmas",
+      category: "modules",
+      icon: TbHandStop,
+      component: <PalmEnrollModule />,
+      keywords: ["palm", "hand", "palma", "module"],
+    },
+    {
+      id: "mod-iris",
+      title: "15. Módulo: Iris",
+      category: "modules",
+      icon: TbEye,
+      component: <IrisEnrollModule />,
+      keywords: ["iris", "eye", "ojo", "module"],
+    },
+    {
+      id: "mod-face",
+      title: "16. Módulo: Facial",
+      category: "modules",
+      icon: TbFaceId,
+      component: <FaceEnrollModule />,
+      keywords: ["face", "facial", "rostro", "camera", "module"],
+    },
+  ];
+
+  const filteredSections = sections.filter(s => {
+    if (!search) return true;
+    const query = search.toLowerCase();
+    return (
+      s.title.toLowerCase().includes(query) ||
+      s.keywords.some(k => k.includes(query))
+    );
+  });
+
+  const categories: { id: SectionCategory; label: string; icon: any }[] = [
+    { id: "basics", label: "Basics & Layout", icon: <TbPalette /> },
+    { id: "data", label: "Data & API", icon: <TbDatabase /> },
+    { id: "advanced", label: "Advanced Customization", icon: <TbCode /> },
+    { id: "modules", label: "Pre-built Modules", icon: <TbPackage /> },
+  ];
+
+  const toggleSection = (id: string) => {
+    setOpenSections(prev => ({ ...prev, [id]: !prev[id] }));
+  };
+
+  if (!mounted) return null;
+
+  return (
+    <div className="min-h-screen bg-background p-4 md:p-8 font-sans transition-colors duration-500">
+      <div className="max-w-5xl mx-auto space-y-10">
+        
+        {/* Header */}
+        <div className="relative pt-12 text-center space-y-4">
+          <div className="inline-flex items-center gap-2 px-4 py-1.5 bg-primary/10 rounded-full text-primary text-xs font-bold uppercase tracking-wider animate-in fade-in duration-700">
+            <TbPackage size={14} />
+            @intell/biometric-sdk v1.0.0
+          </div>
+          <h1 className="text-4xl md:text-5xl font-black text-foreground tracking-tight animate-in slide-in-from-top-4 duration-500">
+             SDK <span className="text-primary italic">Documentation</span>
+          </h1>
+          <p className="text-foreground/60 max-w-2xl mx-auto text-lg leading-relaxed">
+            Explora todas las capacidades, desde componentes pre-hechos hasta personalización total desde cero.
+          </p>
+        </div>
+
+        {/* Search Bar */}
+        <div className="sticky top-6 z-40">
+           <div className="relative group">
+              <div className="absolute inset-0 bg-primary/20 rounded-2xl blur-xl opacity-0 group-focus-within:opacity-100 transition-opacity" />
+              <div className="relative flex items-center bg-card border border-border/50 rounded-2xl p-2 shadow-2xl backdrop-blur-3xl">
+                <div className="flex-1 flex items-center px-4 gap-4">
+                  <TbSearch className="text-foreground/40" size={20} />
+                  <input 
+                    type="text" 
+                    placeholder="Busca por título, componente o funcionalidad... (ej. 'button', 'finger', 'api')" 
+                    className="flex-1 bg-transparent border-none outline-none text-foreground placeholder:text-foreground/30 py-2 text-md"
+                    value={search}
+                    onChange={(e) => setSearch(e.target.value)}
+                  />
+                  {search && (
+                    <button 
+                      onClick={() => setSearch("")}
+                      className="p-1.5 hover:bg-secondary rounded-full transition-colors text-foreground/40 hover:text-foreground"
+                    >
+                      <TbX size={16} />
+                    </button>
+                  )}
+                </div>
+                <div className="hidden md:flex px-4 py-2 border-l border-border/50 text-[10px] items-center gap-3 text-foreground/30 font-bold uppercase tracking-widest">
+                  <span>{filteredSections.length} Resultados</span>
+                </div>
+              </div>
+           </div>
+        </div>
+
+        {/* Categories / Grid */}
+        <div className="space-y-12 pb-24">
+          {categories.map((cat) => {
+            const catSections = filteredSections.filter(s => s.category === cat.id);
+            if (catSections.length === 0) return null;
+
+            return (
+              <div key={cat.id} className="space-y-6">
+                <div className="flex items-center gap-3 pl-2">
+                   <div className="text-primary">{cat.icon}</div>
+                   <h2 className="text-sm font-black uppercase tracking-[0.2em] text-foreground/40">
+                     {cat.label}
+                   </h2>
+                   <div className="flex-1 h-px bg-gradient-to-r from-border/50 to-transparent ml-4" />
+                </div>
+
+                <div className="grid grid-cols-1 gap-6">
+                  {catSections.map((s) => (
+                    <Section 
+                      key={s.id} 
+                      title={s.title} 
+                      icon={s.icon}
+                      isOpen={!!openSections[s.id] || !!search}
+                      onToggle={() => toggleSection(s.id)}
+                    >
+                      {s.component}
+                    </Section>
+                  ))}
+                </div>
+              </div>
+            );
+          })}
+
+          {filteredSections.length === 0 && (
+             <div className="py-20 text-center space-y-4 animate-in fade-in zoom-in duration-300">
+                <div className="w-20 h-20 bg-secondary/50 rounded-full flex items-center justify-center mx-auto text-foreground/20">
+                   <TbSearch size={40} />
+                </div>
+                <div>
+                  <h3 className="text-xl font-bold">No se encontraron resultados</h3>
+                  <p className="text-foreground/40 text-sm">Intenta con otros términos de búsqueda.</p>
+                </div>
+                <Button variant="ghost" onClick={() => setSearch("")}>Limpiar Búsqueda</Button>
+             </div>
+          )}
+        </div>
+      </div>
+      
+      {/* Scroll to top fab can be added here if needed */}
+    </div>
+  );
+}