webs-sdk 0.19.62 → 0.19.65

package/docs/STREAK_IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,430 @@
+# Streak — Guía de implementación
+
+Módulo de racha de actividad del usuario. Muestra un calendario mensual/semanal con los días en que el usuario registró actividad, su racha actual, la mejor racha y una celebración cuando suma un nuevo día.
+
+---
+
+## Índice
+
+1. [Arquitectura](#1-arquitectura)
+2. [Requisito previo: proxy API](#2-requisito-previo-proxy-api)
+3. [Implementación mínima](#3-implementación-mínima)
+4. [Implementación completa con i18n y config remota](#4-implementación-completa-con-i18n-y-config-remota)
+5. [Página dedicada con fondo configurable](#5-página-dedicada-con-fondo-configurable)
+6. [Props de StreakWidget](#6-props-de-streakwidget)
+7. [StreakSdkConfig — configuración de negocio](#7-streaksdkconfig--configuración-de-negocio)
+8. [StreakTexts — i18n](#8-streaktexts--i18n)
+9. [StreakTheme — theming visual](#9-streaktheme--theming-visual)
+10. [CSS Custom Properties — theming sin props](#10-css-custom-properties--theming-sin-props)
+11. [Primitivos avanzados](#11-primitivos-avanzados)
+12. [Checklist de implementación](#12-checklist-de-implementación)
+
+---
+
+## 1. Arquitectura
+
+```
+webs-sdk
+└── StreakWidget          ← punto de entrada recomendado
+    ├── useStreak         ← fetch de datos (agnóstico de portal)
+    ├── StreakCard         ← UI del calendario (mensual + semanal)
+    ├── StreakModal        ← envuelve la card en un modal overlay
+    └── StreakCelebration  ← popup de hito de racha
+
+portal (ej. efcweb)
+└── [Portal]StreakWidget  ← thin wrapper
+    ├── lee sesión y websiteId del store del portal
+    ├── construye `texts` desde i18n del portal
+    └── renderiza <StreakWidget> del SDK con props planas
+```
+
+**Regla de oro:** el portal solo aporta lo que el SDK no puede conocer — sesión, websiteId, router y textos i18n. Todo lo demás lo gestiona el SDK internamente.
+
+---
+
+## 2. Requisito previo: proxy API
+
+El SDK **nunca llama directamente al backend**. El portal debe exponer un endpoint proxy. El SDK llamará a `apiBaseUrl` con `POST` y este body:
+
+```ts
+{ user_id: string; app_user_id: string; website_id: string; keywords: string[]; days: number; }
+```
+
+Respuesta esperada:
+
+```ts
+{ success: 1, data: { "login": ["2026-08-01", "2026-08-02"] } }
+```
+
+### Ejemplo de proxy en Next.js
+
+```ts
+// app/api/streak/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(req: NextRequest) {
+  const body = await req.json();
+  const res = await fetch(`${process.env.BACKEND_URL}/streak/get`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  return NextResponse.json(await res.json());
+}
+```
+
+---
+
+## 3. Implementación mínima
+
+Sin i18n ni config remota. Usa los textos en español por defecto del SDK.
+
+```tsx
+import { StreakWidget } from 'webs-sdk';
+
+function MyStreakPage({ userId, websiteId }: { userId: string; websiteId: string }) {
+  return <StreakWidget userId={userId} websiteId={websiteId} apiBaseUrl="/api/streak" />;
+}
+```
+
+---
+
+## 4. Implementación completa con i18n y config remota
+
+Patrón recomendado para producción. El portal crea un thin wrapper que lee sesión, config remota y textos i18n, y los pasa como props planas al SDK.
+
+```tsx
+// components/streak/PortalStreakWidget.tsx
+'use client';
+
+import { StreakWidget } from 'webs-sdk';
+import type { StreakSdkConfig, StreakTexts, StreakTheme } from 'webs-sdk';
+import { useAuthStore } from '@/store/authStore';       // adaptar al portal
+import { useWebsite } from '@/hooks/useWebsite';         // adaptar al portal
+import { useWebsiteData } from '@/hooks/useWebsiteData'; // adaptar al portal
+import { useRouter } from '@/i18n/navigation';           // adaptar al portal
+import { useTranslations } from 'next-intl';             // adaptar al portal
+
+export function PortalStreakWidget({ asModal = true, className, theme, activityIcon, config }) {
+  const { userSession, isAuthenticated, _hasHydrated } = useAuthStore();
+  const { websiteData } = useWebsite();
+  const { getWebsiteData } = useWebsiteData();
+  const router = useRouter();
+  const t = useTranslations('streak'); // adaptar namespace
+
+  // Config: prop explícita > product_config remoto > defaults del SDK
+  const remoteConfig: StreakSdkConfig | undefined = getWebsiteData('product_config.streak') || undefined;
+  const streakConfig = config ?? remoteConfig;
+
+  // Guard: no renderizar sin sesión o con feature inactivo
+  if (!_hasHydrated || !isAuthenticated || !userSession?.us_id || !websiteData?.web_id || streakConfig?.active === false) {
+    return null;
+  }
+
+  const texts: StreakTexts = {
+    title:                t('title'),
+    subtitle:             t('subtitle'),
+    loading:              t('loading'),
+    errorMessage:         t('errorMessage'),
+    currentStreakLabel:   t('currentStreakLabel'),
+    bestStreakLabel:      t('bestStreakLabel'),
+    streakCountLabel:     t('streakCountLabel', { count: '{count}' }),
+    celebrationTitle:     t('celebrationTitle'),
+    celebrationMessage:   t('celebrationMessage'),
+    closeButton:          t('closeButton'),
+    weekdayLabels:        t('weekdayLabels').split(',').map((s) => s.trim()),
+    calendarLocale:       t('calendarLocale'),
+    prevMonthLabel:       t('prevMonthLabel'),
+    nextMonthLabel:       t('nextMonthLabel'),
+    thisWeekLabel:        t('thisWeekLabel'),
+    switchToWeeklyLabel:  t('switchToWeeklyLabel'),
+    switchToMonthlyLabel: t('switchToMonthlyLabel'),
+  };
+
+  return (
+    <StreakWidget
+      userId={String(userSession.us_id)}
+      websiteId={websiteData.web_id}
+      apiBaseUrl="/api/streak"
+      config={streakConfig}
+      texts={texts}
+      theme={theme}
+      activityIcon={activityIcon}
+      asModal={asModal}
+      className={className}
+      onCtaClick={(action) => router.push(action)}
+    />
+  );
+}
+```
+
+### Claves i18n necesarias
+
+```json
+{
+  "streak": {
+    "title": "Tu racha",
+    "subtitle": "Consigue actividad todos los días para mantener tu racha",
+    "loading": "Cargando tu racha...",
+    "errorMessage": "No se pudo cargar tu racha. Inténtalo más tarde.",
+    "currentStreakLabel": "Racha actual",
+    "bestStreakLabel": "Mejor racha",
+    "streakCountLabel": "{count} días de racha (esta semana)",
+    "celebrationTitle": "¡Racha conseguida!",
+    "celebrationMessage": "Has sumado un nuevo día a tu racha. ¡Sigue así!",
+    "closeButton": "Cerrar",
+    "weekdayLabels": "Lu, Ma, Mi, Ju, Vi, Sa, Do",
+    "calendarLocale": "es-ES",
+    "prevMonthLabel": "Mes anterior",
+    "nextMonthLabel": "Mes siguiente",
+    "thisWeekLabel": "Esta semana",
+    "switchToWeeklyLabel": "Ver semanal",
+    "switchToMonthlyLabel": "Ver mensual"
+  }
+}
+```
+
+---
+
+## 5. Página dedicada con fondo configurable
+
+```tsx
+// app/[locale]/my_account/streak/page.tsx
+'use client';
+
+import { useEffect } from 'react';
+import { useRouter } from '@/i18n/navigation';
+import { useAuthStore } from '@/store/authStore';
+import { useWebsiteData } from '@/hooks/useWebsiteData';
+import { resolveStreakPageBackground, type StreakSdkConfig } from 'webs-sdk';
+import { PortalStreakWidget } from '@/components/streak/PortalStreakWidget';
+
+export default function StreakPage() {
+  const router = useRouter();
+  const { userSession, isAuthenticated, _hasHydrated } = useAuthStore();
+  const { getWebsiteData } = useWebsiteData();
+
+  useEffect(() => {
+    if (_hasHydrated && !isAuthenticated) router.push('/login?redirect=/my_account/streak');
+  }, [_hasHydrated, isAuthenticated, router]);
+
+  if (!_hasHydrated || !isAuthenticated || !userSession) return null;
+
+  // Adaptar la ruta según product_config del portal
+  const childs: StreakSdkConfig[] = getWebsiteData('product_config.my_account.childs') || [];
+  const streakConfig = childs.find((c) => c.key === 'streak');
+
+  if (!streakConfig || streakConfig.active === false) {
+    router.replace('/my_account');
+    return null;
+  }
+
+  const bgStyle = resolveStreakPageBackground(streakConfig.background);
+
+  return (
+    <div className="relative flex flex-col flex-1 w-full" style={{ background: 'var(--color-background, #000000)' }}>
+      <div className="absolute bottom-0 left-0 right-0 h-1/2" style={bgStyle} aria-hidden="true" />
+      <div className="relative z-10 flex flex-col flex-1 w-full">
+        <PortalStreakWidget asModal={false} config={streakConfig} />
+      </div>
+    </div>
+  );
+}
+```
+
+### Valores de `config.background`
+
+| Valor | Resultado |
+|---|---|
+| `undefined` / `""` | `--streak-page-bg` del CSS del tema (fallback: `--primary-500`) |
+| `"none"` | `--color-background` del tema |
+| `"#E4002B"` / `"rgb(...)"` | `background-color` con ese valor |
+| `"https://..."` / `"/img/bg.jpg"` | `background-image: url(...)` con `cover` |
+
+---
+
+## 6. Props de StreakWidget
+
+| Prop | Tipo | Req | Descripción |
+|---|---|---|---|
+| `userId` | `string` | ✅ | ID del usuario autenticado. Sin valor, no hay fetch. |
+| `websiteId` | `string` | ✅ | ID del portal. |
+| `apiBaseUrl` | `string` | ✅ | Ruta del proxy. Ej: `"/api/streak"`. |
+| `config` | `StreakSdkConfig` | — | Configuración de negocio. |
+| `texts` | `StreakTexts` | — | Textos i18n. Default: español. |
+| `theme` | `StreakTheme` | — | Overrides de color. |
+| `activityIcon` | `string` | — | URL de imagen para días completados. |
+| `asModal` | `boolean` | — | `true` = modal overlay. Default: `false`. |
+| `className` | `string` | — | Clase extra sobre el contenedor raíz. |
+---
+
+## 7. StreakSdkConfig — configuración de negocio
+
+Viene de `product_config` del portal. Todos los campos son opcionales.
+
+```ts
+{
+  key?: string;              // identificador, ej. "streak"
+  active?: boolean;          // false → no renderizar. Default: true
+  period?: 'monthly' | 'weekly' | 'both';  // Default: "both"
+  defaultView?: 'monthly' | 'weekly';      // Default: "monthly"
+  icon?: string;             // URL de imagen para días completados
+  keywords?: string[];       // actividades a consultar. Default: ["login"]
+  days?: number;             // rango de días a pedir. Default: 30
+  is_navigable?: boolean;    // muestra botones ‹ ›. Default: true
+  theme?: string;            // nombre del theme CSS → clase "streak-theme-{nombre}"
+  background?: string;       // fondo del área decorativa
+  custom_btn?: {
+    active?: boolean;        // muestra CTA personalizado bajo la card
+    action?: string;         // URL que se recibe en onCtaClick
+  };
+  celebration?: {
+    active?: boolean;        // Default: true
+    icon?: string;           // icono del popup (fallback: config.icon)
+    frequency?: number;      // cada cuántos días celebrar. Default: 1
+  };
+}
+```
+
+---
+
+## 8. StreakTexts — i18n
+
+Todos opcionales. Los no definidos usan el default en español del SDK.
+
+```ts
+{
+  title?: string;
+  subtitle?: string;
+  loading?: string;
+  errorMessage?: string;
+  currentStreakLabel?: string;
+  bestStreakLabel?: string;
+  streakCountLabel?: string;      // usar {count} como placeholder
+  celebrationTitle?: string;
+  celebrationMessage?: string;
+  closeButton?: string;
+  weekdayLabels?: string[];       // ['Lu','Ma','Mi','Ju','Vi','Sa','Do']
+  calendarLocale?: string;        // BCP-47: "es-ES", "en-GB", "fr-FR"...
+  prevMonthLabel?: string;
+  nextMonthLabel?: string;
+  thisWeekLabel?: string;
+  switchToWeeklyLabel?: string;
+  switchToMonthlyLabel?: string;
+}
+```
+
+---
+
+## 9. StreakTheme — theming visual
+
+Solo las claves definidas generan una CSS custom property inline.
+
+```ts
+{
+  primaryColor?: string;           // bordes completados, CTA, dot de hoy
+  cardBackgroundColor?: string;    // fondo del panel del calendario
+  backgroundTopColor?: string;     // mitad superior del fondo decorativo
+  backgroundBottomColor?: string;  // mitad inferior del fondo decorativo
+  pillColor?: string;              // pill de la semana en curso
+  emptyBorderColor?: string;       // borde días vacíos del mes
+  outOfMonthBorderColor?: string;  // borde días de meses adyacentes
+  todayDotColor?: string;          // punto bajo el día de hoy
+  textColor?: string;              // texto principal en el panel
+  mutedTextColor?: string;         // texto secundario en el panel
+  borderColor?: string;            // borde del modal y del panel
+  heroTextColor?: string;          // título/subtítulo fuera del panel
+  heroMutedTextColor?: string;     // subtítulo secundario fuera del panel
+  ctaTextColor?: string;           // texto del botón CTA
+}
+```
+
+---
+
+## 10. CSS Custom Properties — theming sin props
+
+Para themes completos del portal, definir las variables en CSS sin tocar props.
+
+```css
+/* Opción A: apuntar al componente directamente */
+.streak-card {
+  --streak-primary-color:         #E4002B;
+  --streak-card-bg:               #FFFFFF;
+  --streak-bg-top:                #FFFFFF;
+  --streak-bg-bottom:             #FFDCDC;
+  --streak-pill-bg:               #FFDCDC;
+  --streak-empty-border:          #B5B5B5;
+  --streak-out-of-month-border:   #E8E8E8;
+  --streak-today-dot:             #E4002B;
+  --streak-text-color:            #2B2B2B;
+  --streak-muted-text-color:      #6D6665;
+  --streak-border-color:          #E5E5E5;
+  --streak-hero-text-color:       #2B2B2B;
+  --streak-hero-muted-text-color: #6D6665;
+  --streak-cta-text-color:        #FFFFFF;
+}
+```
+
+```css
+/* Opción B: config.theme = "my-portal" → añade clase "streak-theme-my-portal" */
+.streak-theme-my-portal {
+  --streak-primary-color: #E4002B;
+  /* ... resto de variables ... */
+}
+```
+
+---
+
+## 11. Primitivos avanzados
+
+Solo si `StreakWidget` no cubre el caso específico:
+
+```tsx
+import {
+  StreakCard,        // solo el calendario (sin fetch, sin modal, sin celebración)
+  StreakModal,       // modal genérico que envuelve cualquier contenido
+  StreakCelebration, // popup de celebración independiente
+  useStreak,         // hook de fetch puro
+} from 'webs-sdk';
+```
+
+> Usar primitivos solo si hay una razón específica. Para el 99% de los casos `StreakWidget` es suficiente.
+
+---
+
+## 12. Checklist de implementación
+
+### Backend / Proxy
+- [ ] Endpoint proxy creado en el portal (ej. `POST /api/streak`)
+- [ ] El proxy forwardea el body tal cual al backend real
+- [ ] La respuesta tiene la forma `{ success: 1, data: { "login": ["YYYY-MM-DD", ...] } }`
+
+### SDK
+- [ ] `webs-sdk` instalado y actualizado a la versión que incluye `StreakWidget`
+- [ ] `StreakWidget` importado desde `webs-sdk`
+
+### Thin wrapper del portal
+- [ ] Creado `[Portal]StreakWidget` que lee sesión, websiteId y config
+- [ ] Guard implementado: no renderiza sin sesión o con `active === false`
+- [ ] `texts` construido desde el sistema i18n del portal
+- [ ] `onCtaClick` conectado al router del portal
+
+### i18n
+- [ ] Todas las claves de `StreakTexts` añadidas a los archivos de traducción de cada idioma
+- [ ] `weekdayLabels` como string separado por comas (`"Lu, Ma, Mi, ..."`)
+- [ ] `calendarLocale` con el código BCP-47 correcto para cada idioma
+
+### Página dedicada (si aplica)
+- [ ] Ruta creada con guard de autenticación y redirect a `/login`
+- [ ] Guard de feature con redirect si `active === false`
+- [ ] `resolveStreakPageBackground` importado de `webs-sdk` y usado para el fondo
+
+### Visual
+- [ ] Theming aplicado (prop `theme`, CSS variables o `config.theme`)
+- [ ] `activityIcon` configurado si el portal tiene imagen de actividad propia
+- [ ] Validar skeleton de carga en el primer fetch
+- [ ] Validar overlay sutil al navegar entre meses
+- [ ] Validar popup de celebración al sumar un nuevo día de racha
+
+
+

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "webs-sdk",
-  "version": "0.19.62",
+  "version": "0.19.65",
   "private": false,
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "pi": {
+    "skills": ["./skills/webs-sdk-package"]
+  },
+  "bin": {
+    "webs-sdk-skill": "./scripts/install-agent-skill.cjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -21,7 +27,12 @@
   },
   "files": [
     "dist/**/*",
-    "public/**/*"
+    "public/**/*",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "docs/**/*",
+    "skills/**/*",
+    "scripts/install-agent-skill.cjs"
   ],
   "scripts": {
     "dev": "next dev --turbopack",
@@ -29,9 +40,15 @@
     "build:watch": "tsc --project tsconfig.build.json --watch",
     "prepublishOnly": "npm run build",
     "start": "next start",
-    "lint": "next lint"
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:types": "tsc --project tsconfig.tests.json",
+    "test:package": "npm run build && node scripts/check-package.cjs"
   },
   "dependencies": {
+    "@microsoft/clarity": "^1.0.2",
     "@radix-ui/react-accordion": "^1.2.12",
     "@radix-ui/react-alert-dialog": "^1.1.15",
     "@radix-ui/react-aspect-ratio": "^1.1.7",
@@ -46,6 +63,7 @@
     "@radix-ui/react-navigation-menu": "^1.2.14",
     "@radix-ui/react-select": "^2.2.6",
     "@radix-ui/react-separator": "^1.1.7",
+    "@radix-ui/react-slider": "^1.4.7",
     "@radix-ui/react-slot": "^1.2.4",
     "@radix-ui/react-tabs": "^1.1.13",
     "@radix-ui/react-tooltip": "^1.2.8",
@@ -54,6 +72,7 @@
     "dompurify": "^3.4.12",
     "embla-carousel-react": "^8.3.2",
     "hls.js": "^1.6.16",
+    "media-chrome": "^4.19.3",
     "mixpanel-browser": "^2.72.0",
     "motion": "^12.38.0",
     "qrcode": "^1.5.4",
@@ -66,18 +85,22 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@eslint/eslintrc": "^3",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.7",
     "@types/dompurify": "^3.0.5",
     "@types/node": "^24.3.0",
     "@types/qrcode": "^1.5.6",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "@vitest/coverage-v8": "^4.1.11",
     "eslint": "^9",
-    "eslint-config-next": "^15.5.2",
+    "eslint-config-next": "^16.3.7",
+    "jsdom": "^26.1.0",
     "lucide-react": "^1.14.0",
     "next": "^16.0.8",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
   }
 }

package/scripts/install-agent-skill.cjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+'use strict';
+
+// Copy the portable Agent Skills bundle into a consuming project.
+// JavaScript is used because published CLI entry points must run on Node without TS tooling.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.log('Usage: webs-sdk-skill [--force]\nInstall skill into .agents/skills/webs-sdk-package in the current directory.');
+  process.exit(0);
+}
+if (args.some((arg) => arg !== '--force')) {
+  console.error('Unknown option. Use webs-sdk-skill --help.');
+  process.exit(2);
+}
+
+const source = path.resolve(__dirname, '..', 'skills', 'webs-sdk-package');
+const target = path.resolve(process.cwd(), '.agents', 'skills', 'webs-sdk-package');
+if (!fs.existsSync(path.join(source, 'SKILL.md'))) {
+  console.error('Package is missing its agent skill.');
+  process.exit(1);
+}
+if (fs.existsSync(target)) {
+  if (!args.includes('--force')) {
+    console.error(`Skill already exists at ${target}. Run webs-sdk-skill --force to replace it.`);
+    process.exit(1);
+  }
+  fs.rmSync(target, { recursive: true, force: true });
+}
+fs.mkdirSync(path.dirname(target), { recursive: true });
+fs.cpSync(source, target, { recursive: true });
+console.log(`Installed webs-sdk skill at ${target}`);

package/skills/webs-sdk-package/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: webs-sdk-package
+description: Use the webs-sdk npm package in Nexum portals. Activate when choosing or integrating reusable SDK functionality: authentication, sessions, tracking, consent, AI content components, For You, Streak, quiz, esports, Radix UI, VideoPlayer, ConfiguredMediaPlayer, MediaPlayer, or when checking whether the installed package already exports a needed component.
+---
+
+# Use webs-sdk in a portal
+
+1. Read `references/components.md` to choose the existing component or library and its public import path. Read `references/integration.md` for the relevant usage and installation details.
+2. Verify the installed package version and exact public exports/types in `node_modules/webs-sdk/dist/index.d.ts` or `node_modules/webs-sdk/dist/components/ui/index.d.ts`. Catalog is a guide, not an exhaustive or version-independent API contract.
+3. Use `webs-sdk` or `webs-sdk/ui`; never import from private `dist/` paths. Keep default `WebsSDK` singleton out of client components. Add client boundary for interactive React UI. Consult installed `node_modules/webs-sdk/docs/` for feature-specific guidance.
+4. If functionality is absent, report the gap before creating shared functionality in a portal. Add reusable code to the SDK instead.

package/skills/webs-sdk-package/references/components.md

@@ -0,0 +1,30 @@
+# Component and capability map
+
+Choose an existing export before writing portal-specific code. Names below reflect the SDK source at packaging time; the installed package's `.d.ts` files are authoritative. Components accept different Props, API adapters and theme options: inspect their declarations rather than guessing required fields.
+
+## Root entry: `webs-sdk`
+
+| Goal | Exports to inspect | Where it fits |
+| --- | --- | --- |
+| Session, authentication, users, portal metadata | Default `WebsSDK` singleton: `Session`, `AuthManager`, `User`, `Andromeda`, `ContentManager`, `CorporateAuthManager`, `Legal`, `Networking`, `Storage`, `Config`, `.pre` | SDK orchestration, typically server-side in Next.js API routes/middleware. Do not directly bundle default singleton in client UI. |
+| Analytics and consent | `CookieConsent`, `getCookieConsentTexts`, `initGoogleAnalytics`, `updateGAConsent`, `trackGAEvent`, `trackGAPageView`, `isGALoaded`; singleton `MixPanel`, `Clarity`, `Calypso` | Cookie banner and opt-in GA; use consent APIs before loading analytics. |
+| CDN and media checks | `handleCDNRequest`, `validateVideoUrl`, `validateVideoBatch`, `useValidateVideoOnMount`, `useLazyVideoValidation` | CDN route handler, video URL validation and hooks; not a video player. |
+| Image/AI creation | `AvatarAI`, `CreativeFaceSwap`, `Wallpapers`, `WallpapersName`, `AETemplatesSection`, `MemeGenerator`, `Stickers`, `ARFilters`, `ArtGenerator`, `GifsIa`, `QrCode` | Standalone widgets and, where exported, `*Page` and `*ForYouCard` variants. Search Props for API/config/theme requirements. |
+| Other content | `Ringtone`, `Quiz`, `EsportsNews`, `EsportsVideos`, `EsportsLive` | Content widgets, quizzes, esports with API adapter/config types. |
+| For You page | `ForYouFullPage`, `ForYouPage`, `ForYouCard`, individual feature `*Card`, `useAvatarAI`, `useQuiz`, other `use*` hooks | Config-driven feature hub and reusable cards/hooks. Full page has config/theme/translation props; see installed `docs/FOR_YOU_IMPLEMENTATION_GUIDE.md`. |
+| Streak | `StreakWidget`, `StreakCard`, `StreakModal`, `StreakCelebration`, `useStreak` | Activity streak UI and data hook; see installed `docs/STREAK_IMPLEMENTATION_GUIDE.md`. |
+| Login support UI | `PasswordResetRequest`, `PasswordResetForm`, `RecoveryPassword` | Password recovery pieces; not a complete LoginPage. |
+| Forms | `ContactForm`, `ContactFormContent`, `createContactFormAPI` | Reusable configurable contact form. |
+| Networking/dev tools | `NetworkInspectorUI`, `trackRequest`, `trackResponse`, `getLogs`, `clearLogs`, `getStats` | Request inspection in development. |
+| Small utilities | `downloadFile`, `generateQRCode`, `getForYouTranslations`, `forYouFetch` | Reuse instead of copy/pasting helpers. |
+
+## UI entry: `webs-sdk/ui`
+
+| Goal | Export | Decision |
+| --- | --- | --- |
+| Prop-configured video/audio | `ConfiguredMediaPlayer` | Preferred new Radix player for a ready-to-use layout. Set `src`, optional `poster`, `tracks`, `sources`, `controls`; see `references/integration.md` and installed `docs/CONFIGURED_MEDIA_PLAYER.md`. |
+| Custom media controls | `MediaPlayer` plus `MediaPlayerVideo` / `MediaPlayerAudio`, `MediaPlayerControls`, `MediaPlayerPlay`, `MediaPlayerSeek`, `MediaPlayerTime`, `MediaPlayerVolume`, `MediaPlayerSettings`, `MediaPlayerFullscreen`, etc. | Composable Radix parts; root alone does not create media or controls. |
+| Existing/legacy video integration | `VideoPlayer` | Different API (`videoUrl`, `posterImage`, `languages`); retain for existing consumers. |
+| Standard UI primitives | `Button`, `Input`, `Dialog`, `DropdownMenu`, `Tabs`, `Select`, `Tooltip`, `Avatar`, `Accordion`, `Alert`, `Badge`, `Carousel`, `Checkbox`, `NavigationMenu`, `Textarea`, etc. | Use exported Radix primitives; inspect the installed `dist/components/ui/index.d.ts` for full list and types. |
+
+Both entry points have independent barrels. Import from `webs-sdk/ui` for UI, not `webs-sdk` or `webs-sdk/dist/...`. All React UI must run with a suitable client boundary and styling; consult `references/integration.md`.

package/skills/webs-sdk-package/references/integration.md

@@ -0,0 +1,32 @@
+# Install and use the SDK skill
+
+## Portal dependency and agent skill are separate
+
+1. Install the private npm package in the portal (requires registry access): `npm install webs-sdk`.
+2. To make the skill discoverable by Pi and other agents that support the Agent Skills directory convention, run from the portal root: `npm exec -- webs-sdk-skill`. This copies the skill to `.agents/skills/webs-sdk-package/`; commit that directory with the portal if teammates should get the skill. The installer never overwrites an existing installation unless called with `--force`. Restart the agent or reload skills. Installing npm package **alone does not activate** a skill in arbitrary agent tools.
+3. For Pi only, an alternative is `pi install npm:webs-sdk --local`: the package's `pi.skills` manifest enables its skill without copying files into the portal. This does **not** install `webs-sdk` as a dependency of the portal app: do step 1 as well. A personal install omits `--local`. Local Pi packages require project trust. Avoid enabling both paths simultaneously (duplicate skill names).
+4. Agent Skills-compatible tools can also load `skills/webs-sdk-package/SKILL.md` directly from the published package if configured to scan that directory. Other agents may require their own skill configuration.
+
+When upgrading the npm package, rerun `npm exec -- webs-sdk-skill --force` if you copied the skill. The published skill version tracks the npm package, but the installed app dependency, copied skill, and agent's running context can be out of sync. Always check the installed declarations at `node_modules/webs-sdk/dist/index.d.ts` and `node_modules/webs-sdk/dist/components/ui/index.d.ts` before coding.
+
+## Usage patterns
+
+```tsx
+'use client';
+import { ConfiguredMediaPlayer } from 'webs-sdk/ui';
+
+export function Video({ src }: { src: string }) {
+  return <ConfiguredMediaPlayer src={src} controls={{ seekButtons: true, pictureInPicture: true }} />;
+}
+```
+
+For Tailwind CSS v4, the portal CSS must explicitly scan the installed SDK UI directory (normally ignored under `node_modules`): add `@source "../../node_modules/webs-sdk/dist/components/ui";` relative to the CSS file. Adjust depth to the portal layout; without generated utilities UI controls may appear unstyled. Consult `node_modules/webs-sdk/docs/CONFIGURED_MEDIA_PLAYER.md` for props, HLS and captions. `ConfiguredMediaPlayer` and `MediaPlayer` are different from legacy `VideoPlayer`.
+
+```ts
+// In a server-side route/middleware, not a client component:
+import WebsSDK from 'webs-sdk';
+
+const metadata = await WebsSDK.Andromeda.getWebsiteMetadatabyHostname(hostname);
+```
+
+Do not assume a backend response shape, API keys, or portal theme. Inspect the relevant exported Props and feature guide; fetch backend data through the existing server-side pattern. `webs-sdk/ui` is a client-side React entry and does not initialize sessions, authentication or analytics for you.

package/dist/libraries/globals.d.ts

@@ -1,17 +0,0 @@
-declare global {
-    interface Window {
-        __WEBS_SDK_GLOBALS__?: {
-            sessionID: string | null;
-        };
-    }
-}
-export declare const setGlobalSessionID: (sessionID: string | null) => void;
-export declare const getGlobalSessionID: () => string | null;
-export declare const clearGlobalSessionID: () => void;
-declare const _default: {
-    setGlobalSessionID: (sessionID: string | null) => void;
-    getGlobalSessionID: () => string | null;
-    clearGlobalSessionID: () => void;
-};
-export default _default;
-//# sourceMappingURL=globals.d.ts.map

package/dist/libraries/globals.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"globals.d.ts","sourceRoot":"","sources":["../../src/libraries/globals.ts"],"names":[],"mappings":"AAMA,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,MAAM;QACZ,oBAAoB,CAAC,EAAE;YACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;SAC5B,CAAC;KACL;CACJ;AAuBD,eAAO,MAAM,kBAAkB,GAAI,WAAW,MAAM,GAAG,IAAI,KAAG,IAI7D,CAAC;AAKF,eAAO,MAAM,kBAAkB,QAAO,MAAM,GAAG,IAI9C,CAAC;AAKF,eAAO,MAAM,oBAAoB,QAAO,IAIvC,CAAC;;oCAtB4C,MAAM,GAAG,IAAI,KAAG,IAAI;8BAS5B,MAAM,GAAG,IAAI;gCASX,IAAI;;AAM5C,wBAIE"}