webs-sdk 0.19.64 → 0.19.66

package/public/spin2win/fonts/switzer/README.md

@@ -1,23 +1,23 @@
-# Instrucciones para agregar la fuente Switzer
-
-## 📁 Archivos necesarios
-
-Copia los siguientes archivos de la fuente Switzer a esta carpeta:
-
-### Archivos requeridos:
-- `Switzer-Regular.woff2`
-- `Switzer-Regular.woff`
-- `Switzer-Medium.woff2`
-- `Switzer-Medium.woff`
-- `Switzer-Semibold.woff2`
-- `Switzer-Semibold.woff`
-- `Switzer-Bold.woff2`
-- `Switzer-Bold.woff`
-
-## 📝 Notas:
-- Los archivos .woff2 son la versión comprimida (más eficiente)
-- Los archivos .woff son la versión de respaldo para navegadores antiguos
-- La configuración de @font-face ya está lista en `spin2win/styles/fonts.css`
-
-## ✅ Una vez copiados los archivos:
+# Instrucciones para agregar la fuente Switzer
+
+## 📁 Archivos necesarios
+
+Copia los siguientes archivos de la fuente Switzer a esta carpeta:
+
+### Archivos requeridos:
+- `Switzer-Regular.woff2`
+- `Switzer-Regular.woff`
+- `Switzer-Medium.woff2`
+- `Switzer-Medium.woff`
+- `Switzer-Semibold.woff2`
+- `Switzer-Semibold.woff`
+- `Switzer-Bold.woff2`
+- `Switzer-Bold.woff`
+
+## 📝 Notas:
+- Los archivos .woff2 son la versión comprimida (más eficiente)
+- Los archivos .woff son la versión de respaldo para navegadores antiguos
+- La configuración de @font-face ya está lista en `spin2win/styles/fonts.css`
+
+## ✅ Una vez copiados los archivos:
 La fuente Switzer estará disponible automáticamente para el tema `womantoday`.

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,21 @@
+---
+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.
+
+## UI governance (webs-sdk/ui)
+
+**Prefer verified `webs-sdk/ui` exports over direct `@radix-ui` imports or local duplicates.** The SDK supplies many accessible primitives with `data-slot` attributes; check its actual export barrel before choosing one. Avoid direct Radix dependencies where an SDK export exists.
+
+**Structural primitives are largely unbranded.** Style `Button`, `Input`, `Dialog`, `NavigationMenu`, `Card`, etc. with portal CSS tokens and Tailwind classes. Some exports (for example `Skeleton` and media players) do include styles: inspect the installed component before styling. Key gotchas verified in source: `Button` has no `variant`/`size` props; `navigationMenuTriggerStyle()` returns `""`; `Badge` accepts but silently strips its `variant` prop before rendering.
+
+**Do not force a visual redesign** when a parity requirement (legacy andromeda match or Figma spec) exists. Use `webs-sdk/ui` for accessible structure; reproduce the exact visual via CSS.
+
+See `references/ui.md` for styling patterns, the complete verified export map, and what is **not** in the barrel.

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

@@ -0,0 +1,32 @@
+# 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`
+
+Most structural primitives are **unbranded** Radix or native wrappers. Many emit `data-slot` attributes for CSS targeting and forward `className`; some exports (for example `Skeleton` and media players) include built-in classes. Apply portal visuals via `className` or `[data-slot]` selectors. Verify the installed barrel at `node_modules/webs-sdk/dist/components/ui/index.d.ts`; `references/ui.md` lists exceptions and styling patterns.
+
+| 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` (no variants — unstyled slot), `Input`, `Dialog`/parts, `DropdownMenu`/parts, `Tabs`/parts, `Select`/parts, `Tooltip`/parts, `Avatar`/parts, `Accordion`/parts, `Alert`, `Badge` (variant prop stripped), `Carousel`, `Checkbox`, `NavigationMenu`/parts (`navigationMenuTriggerStyle` returns `""`), `Textarea`, `Card`/parts, `Separator`, `Skeleton`, `Field`/parts, `Item`/parts, `InputGroup`/parts, `ButtonGroup`/parts, `Breadcrumb`/parts, `HoverCard`/parts, `AlertDialog`/parts, `Collapsible`/parts, `ContextMenu`/parts, `AspectRatio`, `Label` | Prefer exported primitives over direct `@radix-ui/*` imports when the SDK offers an equivalent. |
+
+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/skills/webs-sdk-package/references/ui.md

@@ -0,0 +1,197 @@
+# webs-sdk/ui — UI governance for portal consumers
+
+Import path: `from 'webs-sdk/ui'`
+Authoritative export list: `node_modules/webs-sdk/dist/components/ui/index.d.ts`
+
+---
+
+## Rule 1 — Prefer existing `webs-sdk/ui` exports over direct `@radix-ui` imports
+
+```ts
+// ✅ Correct
+import { Dialog, DialogContent, DialogTrigger } from 'webs-sdk/ui';
+import { Tabs, TabsList, TabsTrigger, TabsContent } from 'webs-sdk/ui';
+import { NavigationMenu, NavigationMenuList, NavigationMenuItem } from 'webs-sdk/ui';
+
+// ❌ Wrong — creates version drift, duplicate bundle, breaks governance
+import * as DialogPrimitive from '@radix-ui/react-dialog';
+```
+
+The SDK exports many Radix-backed primitives with `data-slot` attributes. Verify the barrel first; use existing exports rather than duplicating them locally. Direct Radix imports for already-exported primitives risk version drift.
+
+If a primitive you need is **missing from `webs-sdk/ui`**: report the gap and add it to the SDK source (`src/components/ui/`) rather than adding a direct Radix dep to the portal.
+
+---
+
+## Rule 2 — Primitives are intentionally unstyled; you own all visual CSS
+
+Most structural components wrap a Radix primitive or native element, expose a `data-slot` attribute and forward applicable props including `className`. Check each export for exceptions and built-in styles rather than assuming every primitive has the same implementation.
+
+**Exceptions with minimal built-in classes:**
+- `TooltipContent` — positioning and open/close animation classes
+- `Skeleton` — `animate-pulse rounded-md bg-muted`
+- `ConfiguredMediaPlayer` / `media-player` — rich layout classes for media controls
+
+**Verified gotchas** (do not assume CVA variants exist):
+
+| Component | Gotcha |
+|---|---|
+| `Button` | **No `variant` or `size` props.** Plain unstyled slot. Add your own via `className`. |
+| `navigationMenuTriggerStyle()` | **Returns `""`** (empty string). Apply link/trigger styles yourself. |
+| `Badge` | Accepts `variant?: "default"\|"outline"\|"secondary"\|"destructive"` but **silently strips it** before rendering. No variant classes are applied. |
+| `Item` | Has `variant`/`size` props but outputs empty CVA strings — they become `data-variant`/`data-size` DOM attributes for CSS targeting only. |
+
+---
+
+## Rule 3 — Style via `className` or `[data-slot]` CSS; keep primitives unbranded
+
+### Pattern A — inline `className` (component-level)
+
+```tsx
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from 'webs-sdk/ui';
+
+<Dialog>
+  <DialogTrigger className="rounded-full bg-[var(--color-primary)] px-6 py-2 text-sm font-semibold">
+    Open
+  </DialogTrigger>
+  <DialogContent className="rounded-2xl bg-[var(--color-bg-card)] border border-[var(--color-border)] p-8 max-w-lg">
+    <DialogHeader className="mb-4">
+      <DialogTitle className="text-xl font-semibold text-[--color-text-base]">
+        Title
+      </DialogTitle>
+    </DialogHeader>
+  </DialogContent>
+</Dialog>
+```
+
+### Pattern B — `[data-slot]` in `globals.css` (theme-wide)
+
+```css
+/* globals.css — applies to all Dialog instances in the portal */
+[data-slot="dialog-content"] {
+  border-radius: 1rem;
+  background: var(--color-bg-card);
+  border: 1px solid var(--color-border);
+  padding: 2rem;
+}
+[data-slot="dialog-title"] {
+  font-size: 1.25rem;
+  font-weight: 600;
+  color: var(--color-text-base);
+}
+```
+
+### Pattern C — thin portal wrapper (Figma-exact layout)
+
+Wrap `webs-sdk/ui` parts in a portal component when you need Figma-specific structure (custom close icon, extra sections, specific variants):
+
+```tsx
+// src/components/ui/PortalDialog.tsx
+'use client';
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from 'webs-sdk/ui';
+import { cn } from '@/lib/utils';
+
+export function PortalDialog({ title, trigger, children, className }: Props) {
+  return (
+    <Dialog>
+      <DialogTrigger asChild>{trigger}</DialogTrigger>
+      <DialogContent className={cn('rounded-2xl bg-[var(--color-bg-card)] p-8', className)}>
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+        </DialogHeader>
+        {children}
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+---
+
+## Rule 4 — Parity requirement overrides design system preference
+
+When a portal must match legacy andromeda visually (or a Figma spec produced before this governance rule), **do not force a redesign**. Use `webs-sdk/ui` for accessible behaviour; reproduce the legacy visual exactly via CSS custom properties. Parity wins.
+
+---
+
+## NavigationMenu — navbar pattern
+
+`navigationMenuTriggerStyle()` returns `""` — do not call it expecting classes:
+
+```tsx
+import { NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuLink } from 'webs-sdk/ui';
+
+<NavigationMenu className="hidden md:flex">
+  <NavigationMenuList className="flex items-center gap-1">
+    {pages.map(page => (
+      <NavigationMenuItem key={page.url}>
+        <NavigationMenuLink
+          href={page.url}
+          className="rounded-lg px-4 py-2 text-sm font-medium text-[var(--color-text-base)] hover:bg-[var(--color-bg-hover)]"
+        >
+          {page.label}
+        </NavigationMenuLink>
+      </NavigationMenuItem>
+    ))}
+  </NavigationMenuList>
+</NavigationMenu>
+```
+
+---
+
+## Tailwind v4 scan — required for ConfiguredMediaPlayer
+
+`webs-sdk/ui` components that use Tailwind classes (media players, Skeleton, TooltipContent) are inside `node_modules`, which Tailwind v4 does not scan by default. Without this, player controls appear unstyled:
+
+```css
+/* portal globals.css or main CSS file */
+@source "../../node_modules/webs-sdk/dist/components/ui";
+/* adjust relative path to match where this CSS file lives */
+```
+
+See `node_modules/webs-sdk/docs/CONFIGURED_MEDIA_PLAYER.md` for the canonical path example.
+
+---
+
+## What is NOT in `webs-sdk/ui` (verify before use)
+
+The following are **not** confirmed exports in the barrel at time of writing — always check `node_modules/webs-sdk/dist/components/ui/index.d.ts`:
+
+- `Popover` (not exported)
+- `Switch`
+- `RadioGroup`
+- `Progress`
+- `Slider` (as a named export — Radix slider dep exists but verify export)
+
+Never assume a component is available because a similar shadcn component exists. Verify, then use.
+
+---
+
+## Design token conventions (portals)
+
+Portal tokens live in `globals.css` under `:root` and `@theme inline` (Tailwind v4):
+
+```css
+:root {
+  --portal-primary: #ff8546;
+  --portal-card: #1a1a1a;
+  --portal-text: #fdfbff;
+  --portal-border: rgba(255,255,255,0.12);
+  --color-primary: var(--portal-primary);
+  --color-bg-card: var(--portal-card);
+  --color-text-base: var(--portal-text);
+  --color-border: var(--portal-border);
+}
+
+@theme inline {
+  --color-primary: var(--portal-primary);
+  --color-card: var(--portal-card);
+}
+```
+
+Reference in component `className`:
+```tsx
+<Card className="bg-card border border-[var(--portal-border)] rounded-2xl p-6">
+```
+
+Keep primitives unbranded (no portal-specific defaults baked in). In `next_template`, put shared tokens in `src/styles/globals.css` and portal overrides in `public/themes/{name}.css` loaded after it; follow the consumer's actual theme setup.