@uservibesos/web-component 1.0.0

package/README.md

@@ -0,0 +1,533 @@
+# @uservibeos/web-component
+
+**Authenticated** Feature Request Widget as a Web Component (Custom Element).
+
+⚠️ **API KEY REQUIRED** - This widget requires authentication. Only compatible with server-rendered applications.
+
+## Installation
+
+### Via CDN (Recommended)
+
+Add the script tag to your HTML:
+
+```html
+<script src="https://app.uservibeos.com/widget-assets/v1.0.0/widget.js"></script>
+```
+
+### Via NPM
+
+```bash
+npm install @uservibeos/web-component
+```
+
+Then import in your JavaScript:
+
+```javascript
+import '@uservibeos/web-component';
+```
+
+## Usage
+
+### Prerequisites
+- Server-rendered application (Next.js, Remix, SvelteKit, etc.)
+- UserVibeOS API key stored in environment variables
+
+**NOT compatible with:**
+- Static HTML sites
+- Client-only React/Vue apps
+- WordPress (unless using custom server integration)
+
+### Required Attributes
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project` | string | **YES** | Your project slug from UserVibeOS dashboard |
+| `api-key` | string | **YES** | Your UserVibeOS API key from environment variables |
+
+### Optional Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `theme` | `'light' \| 'dark'` | `'light'` | Color theme |
+| `height` | string | `'600px'` | Widget height (CSS value) |
+| `base-url` | string | Auto-detected | Custom base URL (for development/self-hosting) |
+
+### Security Requirements 🔒
+
+**API keys are MANDATORY:**
+- ✅ Widgets will NOT load without a valid API key
+- ✅ API key must come from environment variables
+- ✅ Only use in server-rendered applications
+- ❌ Never hardcode API keys in HTML or JavaScript
+- ❌ Not compatible with static sites or client-only apps
+
+### Events
+
+The widget emits custom events you can listen to:
+
+```javascript
+const widget = document.querySelector('uservibe-widget');
+
+widget.addEventListener('request-submitted', (event) => {
+  console.log('New request submitted:', event.detail);
+});
+
+widget.addEventListener('vote-added', (event) => {
+  console.log('Vote added:', event.detail);
+});
+```
+
+## Examples
+
+### Next.js App Router (Recommended)
+
+**Step 1:** Add your API key to `.env.local`:
+```bash
+USERVIBE_API_KEY=uv_live_your_key_here
+```
+
+**Step 2:** Add to `.gitignore`:
+```
+.env.local
+```
+
+**Step 3:** Use in your server component:
+```tsx
+// app/feedback/page.tsx (Next.js App Router Server Component)
+export default function FeedbackPage() {
+  return (
+    <div>
+      <h1>Feature Requests</h1>
+      <script src="https://app.uservibeos.com/widget-assets/v1.0.0/widget.js"></script>
+      <uservibe-widget
+        project="my-app"
+        api-key={process.env.USERVIBE_API_KEY}
+        theme="light"
+      />
+    </div>
+  );
+}
+```
+
+### With Custom Styling
+
+```tsx
+<uservibe-widget
+  project="my-app"
+  api-key={process.env.USERVIBE_API_KEY}
+  theme="dark"
+  height="800px"
+/>
+
+### Development/Local Testing
+
+When testing locally with UserVibeOS running on a different port:
+
+```tsx
+// Test app on localhost:3002, UserVibeOS on localhost:3000
+export default function TestPage() {
+  return (
+    <div>
+      <script src="http://localhost:3000/widget-assets/v1.0.0/widget.js"></script>
+      <uservibe-widget
+        project="my-app"
+        base-url="http://localhost:3000"
+        api-key={process.env.USERVIBE_API_KEY}
+      />
+    </div>
+  );
+}
+```
+
+Don't forget to add TypeScript types:
+
+```typescript
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      'uservibe-widget': {
+        project: string;
+        'api-key': string; // REQUIRED
+        theme?: 'light' | 'dark';
+        height?: string;
+        'base-url'?: string;
+      };
+    }
+  }
+}
+```
+
+## 🔐 Two-Tier Security Model
+
+UserVibeOS offers two security tiers for widget authentication. Choose based on your security requirements.
+
+---
+
+### TIER 1: Public Keys (PK) - Recommended for Most Users
+
+**Best for:** Standard web applications with good security needs.
+
+**How it works:**
+- Create a Public Key (PK) in the API Keys dashboard
+- Configure allowed origins (up to 5 domains)
+- Use server-side rendering to inject the key
+- Widget validates origin against your whitelist
+
+**Security features:**
+- ✅ Origin/referrer enforcement
+- ✅ Rate limiting (5 req/min per IP/fingerprint)
+- ✅ Advanced browser fingerprinting
+- ✅ Behavioral anomaly detection
+- ✅ Real-time security event logging
+
+**Setup:**
+```bash
+# .env.local
+USERVIBE_PUBLIC_KEY=pk_live_your_key_here
+```
+
+```tsx
+// app/feedback/page.tsx (Next.js Server Component)
+export default function FeedbackPage() {
+  return (
+    <div>
+      <script src="https://app.uservibeos.com/widget-assets/v1.0.0/widget.js"></script>
+      <uservibe-widget
+        project="my-app"
+        api-key={process.env.USERVIBE_PUBLIC_KEY}
+        theme="light"
+      />
+    </div>
+  );
+}
+```
+
+**Limitations:**
+- Keys visible in browser's view source
+- Relies on origin validation (can be bypassed by determined attackers)
+- Not suitable for high-security applications
+
+---
+
+### TIER 2: JWT Proxy - Maximum Security
+
+**Best for:** Financial apps, healthcare, or maximum security requirements.
+
+**How it works:**
+1. Your backend securely holds your Secret Key (SK)
+2. Widget calls YOUR backend proxy endpoint (not UserVibeOS directly)
+3. Your backend exchanges SK for a short-lived JWT token (5 min expiry)
+4. Backend forwards request to UserVibeOS with JWT
+5. **Secret Key never leaves your server**
+
+**Security features:**
+- ✅ All Tier 1 features PLUS:
+- ✅ Secret Key (SK) never exposed to client
+- ✅ JWT tokens expire in 5 minutes
+- ✅ One-time use tokens (replay protection)
+- ✅ Backend request validation
+- ✅ Full cryptographic signing
+- ✅ Complete audit trail
+
+---
+
+### Tier 2 Implementation Guide
+
+#### Step 1: Enable JWT in Project Settings
+
+1. Go to your UserVibeOS Dashboard → Projects → [Your Project]
+2. Navigate to "Project Settings"
+3. Enable "JWT Authentication (Tier 2)"
+4. Select or create a Secret Key (SK)
+5. Set token expiry (default: 5 minutes)
+
+---
+
+#### Step 2: Create Backend Proxy
+
+Choose your framework:
+
+**Next.js App Router:**
+
+```typescript
+// app/api/uservibe-proxy/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+// Token cache (use Redis in production for multi-instance)
+let tokenCache: { token: string; expiresAt: number } | null = null;
+
+async function getValidToken(projectId: string): Promise<string> {
+  // Check cache
+  if (tokenCache && tokenCache.expiresAt > Date.now() + 60000) {
+    return tokenCache.token;
+  }
+
+  // Exchange Secret Key for JWT token
+  const response = await fetch('https://app.uservibeos.com/api/token/exchange', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      secretKey: process.env.USERVIBE_SECRET_KEY, // SK never exposed
+      projectId,
+      origin: process.env.NEXT_PUBLIC_SITE_URL || 'https://yourapp.com',
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error('Token exchange failed');
+  }
+
+  const data = await response.json();
+
+  // Cache token
+  tokenCache = {
+    token: data.token,
+    expiresAt: data.expiresAt,
+  };
+
+  return data.token;
+}
+
+export async function POST(req: NextRequest) {
+  try {
+    const body = await req.json();
+    const { projectId, action, ...payload } = body;
+
+    // Get valid JWT token
+    const jwtToken = await getValidToken(projectId);
+
+    // Forward to Convex with JWT
+    const convexUrl = process.env.CONVEX_URL || 'https://your-deployment.convex.cloud';
+    const response = await fetch(`${convexUrl}/api/function/${action}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${jwtToken}`,
+      },
+      body: JSON.stringify(payload),
+    });
+
+    const data = await response.json();
+    return NextResponse.json(data);
+
+  } catch (error) {
+    console.error('Proxy error:', error);
+    return NextResponse.json(
+      { error: 'Proxy request failed' },
+      { status: 500 }
+    );
+  }
+}
+```
+
+**Express.js:**
+
+```javascript
+// server.js
+const express = require('express');
+const app = express();
+
+let tokenCache = null;
+
+async function getValidToken(projectId) {
+  if (tokenCache && tokenCache.expiresAt > Date.now() + 60000) {
+    return tokenCache.token;
+  }
+
+  const response = await fetch('https://app.uservibeos.com/api/token/exchange', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      secretKey: process.env.USERVIBE_SECRET_KEY,
+      projectId,
+      origin: process.env.SITE_URL || 'https://yourapp.com',
+    }),
+  });
+
+  const data = await response.json();
+  tokenCache = { token: data.token, expiresAt: data.expiresAt };
+  return data.token;
+}
+
+app.post('/api/uservibe-proxy', async (req, res) => {
+  try {
+    const { projectId, action, ...payload } = req.body;
+    const token = await getValidToken(projectId);
+
+    const convexUrl = process.env.CONVEX_URL;
+    const response = await fetch(`${convexUrl}/api/function/${action}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`,
+      },
+      body: JSON.stringify(payload),
+    });
+
+    const data = await response.json();
+    res.json(data);
+  } catch (error) {
+    console.error('Proxy error:', error);
+    res.status(500).json({ error: 'Proxy request failed' });
+  }
+});
+
+app.listen(3000);
+```
+
+---
+
+#### Step 3: Configure Widget for JWT Mode
+
+```html
+<script src="https://app.uservibeos.com/widget-assets/v1.0.0/widget.js"></script>
+<uservibe-widget
+  project="my-app"
+  jwt-mode="true"
+  proxy-url="/api/uservibe-proxy"
+  theme="light"
+></uservibe-widget>
+```
+
+**Key attributes for Tier 2:**
+- `jwt-mode="true"` - Enables JWT authentication mode
+- `proxy-url="/api/uservibe-proxy"` - Your backend proxy endpoint
+
+---
+
+#### Step 4: Environment Variables
+
+```bash
+# .env.local (Backend only - NEVER commit)
+
+# Tier 2: Secret Key (SK) for JWT signing
+USERVIBE_SECRET_KEY=sk_live_your_secret_key_here
+
+# Your Convex deployment URL
+CONVEX_URL=https://your-deployment.convex.cloud
+
+# Your site URL (for origin validation)
+NEXT_PUBLIC_SITE_URL=https://yourapp.com
+```
+
+---
+
+### Production Considerations for Tier 2
+
+#### Token Caching
+
+**Single-instance deployments** (Vercel Hobby, single server):
+- Use in-memory caching (as shown above)
+
+**Multi-instance deployments** (Vercel Pro, load-balanced):
+- Use Redis or similar distributed cache
+- Share tokens across instances
+
+```typescript
+// Example with Upstash Redis
+import { Redis } from '@upstash/redis';
+
+const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_URL!,
+  token: process.env.UPSTASH_REDIS_TOKEN!,
+});
+
+async function getValidToken(projectId: string): Promise<string> {
+  const cacheKey = `uservibe:jwt:${projectId}`;
+
+  // Check cache
+  const cached = await redis.get<{ token: string; expiresAt: number }>(cacheKey);
+  if (cached && cached.expiresAt > Date.now() + 60000) {
+    return cached.token;
+  }
+
+  // Exchange for new token
+  const token = await exchangeToken(projectId);
+
+  // Cache with TTL (4 min, tokens expire in 5)
+  await redis.setex(cacheKey, 240, token);
+
+  return token.token;
+}
+```
+
+#### Error Handling
+
+Always implement graceful error handling:
+
+```typescript
+try {
+  const token = await getValidToken(projectId);
+  // Use token...
+} catch (error) {
+  console.error('JWT token exchange failed:', error);
+
+  // Return user-friendly error
+  return NextResponse.json(
+    { error: 'Authentication failed. Please try again.' },
+    { status: 503 }
+  );
+}
+```
+
+---
+
+### Complete Implementation Guides
+
+For detailed, framework-specific guides:
+
+- 📘 [Next.js App Router Proxy Guide](https://github.com/uservibeOS/uservibeOS/blob/main/docs/jwt-proxy-nextjs.md)
+- 📗 [React + Express Proxy Guide](https://github.com/uservibeOS/uservibeOS/blob/main/docs/jwt-proxy-react-express.md)
+- 📕 [Standalone Express Proxy Guide](https://github.com/uservibeOS/uservibeOS/blob/main/docs/jwt-proxy-express.md)
+- 📙 [Migration Guide: Upgrading to Two-Tier Security](https://github.com/uservibeOS/uservibeOS/blob/main/docs/migration-guide-two-tier-security.md)
+
+---
+
+## API Key Security Best Practices 🔒
+
+### Required Security Practices (Both Tiers)
+
+✅ **MUST DO:**
+- Store API keys in `.env.local` (never in code)
+- Add `.env.local` to `.gitignore`
+- Use server-side rendering only (Next.js Server Components, Remix loaders, etc.)
+- Use different API keys for development and production
+- Rotate API keys if compromised
+
+❌ **NEVER DO:**
+- Hardcode API keys in HTML, JavaScript, or TSX files
+- Commit API keys to version control (GitHub, GitLab, etc.)
+- Use this widget in static HTML sites
+- Use this widget in client-only React/Vue apps
+- Expose API keys in client-side environment variables (NEXT_PUBLIC_, VITE_, etc.)
+- Share API keys in public repositories or screenshots
+
+### Tier 1 vs Tier 2: When to Use
+
+| Use Case | Recommended Tier | Reason |
+|----------|-----------------|---------|
+| Standard web app | Tier 1 (PK) | Good security, easier setup |
+| Financial services | Tier 2 (JWT) | Regulatory compliance |
+| Healthcare (HIPAA) | Tier 2 (JWT) | Maximum security required |
+| E-commerce | Tier 1 or 2 | Depends on sensitivity |
+| Internal tools | Tier 1 (PK) | Lower risk, simpler |
+| Public-facing SaaS | Tier 2 (JWT) | Higher attack surface |
+
+### Important Notes
+
+⚠️ **Tier 1 Limitation**: Public Keys visible in browser's view source (but origin-restricted)
+
+⚠️ **Tier 2 Requirement**: Requires backend infrastructure to run proxy
+
+⚠️ **Not for Static Sites**: Both tiers require server-side rendering
+
+## Browser Support
+
+- Chrome/Edge: ✅
+- Firefox: ✅
+- Safari: ✅
+- IE11: ❌ (Custom Elements not supported)
+
+## License
+
+MIT

package/build.js

@@ -0,0 +1,47 @@
+const esbuild = require('esbuild');
+const fs = require('fs');
+const path = require('path');
+
+const isWatch = process.argv.includes('--watch');
+
+const buildOptions = {
+  entryPoints: ['src/widget.ts'],
+  bundle: true,
+  minify: !isWatch,
+  sourcemap: isWatch,
+  format: 'iife',
+  target: ['es2020'],
+  outfile: 'dist/widget.js',
+  platform: 'browser',
+  logLevel: 'info',
+};
+
+async function build() {
+  try {
+    if (isWatch) {
+      const ctx = await esbuild.context(buildOptions);
+      await ctx.watch();
+      console.log('👀 Watching for changes...');
+    } else {
+      await esbuild.build(buildOptions);
+
+      // Also copy to public directory for CDN
+      const publicDir = path.join(__dirname, '../../public/widget-assets/v1.0.0');
+      if (!fs.existsSync(publicDir)) {
+        fs.mkdirSync(publicDir, { recursive: true });
+      }
+      fs.copyFileSync(
+        path.join(__dirname, 'dist/widget.js'),
+        path.join(publicDir, 'widget.js')
+      );
+
+      console.log('✅ Build complete!');
+      console.log('📦 Copied to public/widget-assets/v1.0.0/widget.js');
+    }
+  } catch (error) {
+    console.error('❌ Build failed:', error);
+    process.exit(1);
+  }
+}
+
+build();

package/dist/widget.js

@@ -0,0 +1,44 @@
+"use strict";(()=>{var i=class extends HTMLElement{constructor(){super();this.iframe=null;this.baseUrl="https://app.uservibesos.com";this.attachShadow({mode:"open"})}static get observedAttributes(){return["project","theme","height","mode","base-url","api-key","jwt-mode","proxy-url"]}connectedCallback(){this.render()}attributeChangedCallback(e,t,o){t!==o&&this.render()}render(){let e=this.getAttribute("project"),t=this.getAttribute("theme")||"light",o=this.getAttribute("height")||"600px",s=this.getAttribute("mode")||"feature",d=this.getAttribute("base-url"),n=this.getAttribute("api-key"),l=this.getAttribute("jwt-mode")==="true",a=this.getAttribute("proxy-url");if(!e){this.renderError('Missing required "project" attribute');return}d?this.baseUrl=d:typeof window<"u"&&window.location.hostname==="localhost"&&(this.baseUrl=window.location.origin);let r=`${this.baseUrl}/widget/${e}`;if(!n&&!l){let h="/api/uservibes-proxy",u=typeof window<"u"?`${window.location.origin}${h}`:h;r+=`?tier=2&proxyUrl=${encodeURIComponent(u)}&mode=${s}`,console.log("[Web Component] TIER 2 auto-detected (no api-key) - using proxy:",u)}else if(l&&a)r+=`?tier=2&proxyUrl=${encodeURIComponent(a)}&mode=${s}`,console.log("[Web Component] TIER 2 legacy mode - using custom proxy:",a);else if(n)r+=`?publicKey=${encodeURIComponent(n)}&mode=${s}`,console.log("[Web Component] TIER 1 mode - using public key");else{this.renderError('Widget requires either an "api-key" attribute for Tier 1 security, or no api-key for Tier 2 security (proxy mode). For Tier 2, ensure you have implemented the proxy at /api/uservibes-proxy.');return}let p=`
+      <style>
+        :host {
+          display: block;
+          width: 100%;
+        }
+        iframe {
+          width: 100%;
+          height: ${o};
+          border: none;
+          border-radius: 8px;
+          overflow: hidden;
+        }
+        .error {
+          padding: 2rem;
+          text-align: center;
+          border: 1px solid #ef4444;
+          border-radius: 8px;
+          background: #fef2f2;
+          color: #991b1b;
+        }
+      </style>
+    `,c=`
+      <iframe
+        src="${r}"
+        title="${e} Feature Requests"
+        loading="lazy"
+        allow="clipboard-write"
+      ></iframe>
+    `;this.shadowRoot&&(this.shadowRoot.innerHTML=p+c,this.iframe=this.shadowRoot.querySelector("iframe"),this.setupMessageListener())}renderError(e){let t=`
+      <style>
+        .error {
+          padding: 2rem;
+          text-align: center;
+          border: 1px solid #ef4444;
+          border-radius: 8px;
+          background: #fef2f2;
+          color: #991b1b;
+        }
+      </style>
+      <div class="error">
+        <strong>Widget Error:</strong> ${e}
+      </div>
+    `;this.shadowRoot&&(this.shadowRoot.innerHTML=t)}setupMessageListener(){window.addEventListener("message",e=>{e.origin===this.baseUrl&&(e.data.type==="USERVIBES_HEIGHT_UPDATE"&&this.iframe&&(this.iframe.style.height=`${e.data.height}px`),e.data.type==="USERVIBES_REQUEST_SUBMITTED"&&this.dispatchEvent(new CustomEvent("request-submitted",{detail:e.data.payload})),e.data.type==="USERVIBES_VOTE_ADDED"&&this.dispatchEvent(new CustomEvent("vote-added",{detail:e.data.payload})))})}};typeof window<"u"&&!customElements.get("uservibes-widget")&&customElements.define("uservibes-widget",i);var b=i;})();

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@uservibesos/web-component",
+  "version": "1.0.0",
+  "description": "Feature request widget as a Web Component",
+  "main": "dist/widget.js",
+  "scripts": {
+    "build": "node build.js",
+    "dev": "node build.js --watch"
+  },
+  "keywords": [
+    "feature-request",
+    "web-component",
+    "custom-element",
+    "widget"
+  ],
+  "author": "UserVibesOS",
+  "license": "MIT",
+  "devDependencies": {
+    "esbuild": "^0.24.0"
+  }
+}

package/src/widget.ts

@@ -0,0 +1,244 @@
+/**
+ * UserVibesOS Feature Request Widget - Web Component
+ *
+ * A custom element that embeds authenticated feature request widgets.
+ *
+ * TWO-TIER SECURITY MODEL:
+ *
+ * TIER 1: Public Keys (PK) - Recommended for most users
+ * - Origin enforcement + Rate limiting + Fingerprinting
+ * - Safe to use with server-side rendering
+ *
+ * TIER 2: JWT Tokens - Maximum security
+ * - Short-lived tokens (5min) + Backend proxy required
+ * - One-time use + Request signing
+ * - Auto-detected when no api-key is present
+ *
+ * ========================================
+ * TIER 1 USAGE (Public Keys - Recommended)
+ * ========================================
+ *
+ * Step 1: Create Public Key (PK) in UserVibesOS dashboard with allowed origins
+ * Step 2: Add to .env.local
+ * USERVIBES_PUBLIC_KEY=pk_live_your_public_key_here
+ *
+ * Step 3: Use in server component
+ * <script src="https://app.uservibesos.com/widget-assets/v1.0.0/widget.js"></script>
+ * <uservibes-widget
+ *   project="my-project-slug"
+ *   api-key={process.env.USERVIBES_PUBLIC_KEY}
+ * ></uservibes-widget>
+ *
+ * ========================================
+ * TIER 2 USAGE (Maximum Security - Auto-detected)
+ * ========================================
+ *
+ * Step 1: Enable Tier 2 mode in project settings
+ * Step 2: Implement backend proxy at /api/uservibes-proxy
+ * Step 3: Use widget WITHOUT api-key (auto-detects Tier 2)
+ *
+ * <script src="https://app.uservibesos.com/widget-assets/v1.0.0/widget.js"></script>
+ * <uservibes-widget
+ *   project="my-project-slug"
+ * ></uservibes-widget>
+ *
+ * The widget automatically detects Tier 2 mode when:
+ * - No api-key attribute is present
+ * - Makes requests to /api/uservibes-proxy (standard path)
+ *
+ * Attributes:
+ * - project (required): Your project slug
+ * - api-key (Tier 1 only): Public Key from environment variables
+ * - mode (optional): "feature" or "roadmap" (default: "feature")
+ * - theme (optional): "light" or "dark" (default: "light")
+ * - height (optional): Height of the widget (default: "600px")
+ * - base-url (optional): Custom base URL (for development/self-hosting)
+ *
+ * DEPRECATED (for backward compatibility only):
+ * - jwt-mode: No longer needed, auto-detected
+ * - proxy-url: Uses standard /api/uservibes-proxy path
+ *
+ * SECURITY:
+ * - TIER 1: Store Public Key in environment variables
+ * - TIER 2: No keys in client code, all handled by proxy
+ * - NEVER commit .env files to version control
+ */
+
+class UserVibesWidget extends HTMLElement {
+  private iframe: HTMLIFrameElement | null = null;
+  private baseUrl: string = 'https://app.uservibesos.com';
+
+  constructor() {
+    super();
+
+    // Use Shadow DOM for style isolation
+    this.attachShadow({ mode: 'open' });
+  }
+
+  static get observedAttributes() {
+    return ['project', 'theme', 'height', 'mode', 'base-url', 'api-key', 'jwt-mode', 'proxy-url'];
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  attributeChangedCallback(name: string, oldValue: string, newValue: string) {
+    if (oldValue !== newValue) {
+      this.render();
+    }
+  }
+
+  private render() {
+    const project = this.getAttribute('project');
+    const theme = this.getAttribute('theme') || 'light';
+    const height = this.getAttribute('height') || '600px';
+    const mode = this.getAttribute('mode') || 'feature';
+    const customBaseUrl = this.getAttribute('base-url');
+    const apiKey = this.getAttribute('api-key');
+
+    // For backward compatibility, check legacy jwt-mode and proxy-url attributes
+    const legacyJwtMode = this.getAttribute('jwt-mode') === 'true';
+    const legacyProxyUrl = this.getAttribute('proxy-url');
+
+    if (!project) {
+      this.renderError('Missing required "project" attribute');
+      return;
+    }
+
+    // Use custom base URL if provided, otherwise use local URL in development
+    if (customBaseUrl) {
+      this.baseUrl = customBaseUrl;
+    } else if (typeof window !== 'undefined' && window.location.hostname === 'localhost') {
+      this.baseUrl = window.location.origin;
+    }
+
+    // Build widget URL - ALWAYS points to UserVibesOS
+    let widgetUrl = `${this.baseUrl}/widget/${project}`;
+
+    // AUTO-DETECT SECURITY TIER
+    if (!apiKey && !legacyJwtMode) {
+      // TIER 2: Auto-detected - No api-key means proxy mode
+      // Build absolute proxy URL from current page origin
+      const standardProxyPath = '/api/uservibes-proxy';
+      const absoluteProxyUrl = typeof window !== 'undefined'
+        ? `${window.location.origin}${standardProxyPath}`
+        : standardProxyPath;
+      widgetUrl += `?tier=2&proxyUrl=${encodeURIComponent(absoluteProxyUrl)}&mode=${mode}`;
+      console.log('[Web Component] TIER 2 auto-detected (no api-key) - using proxy:', absoluteProxyUrl);
+    } else if (legacyJwtMode && legacyProxyUrl) {
+      // LEGACY: Explicit JWT mode with custom proxy URL (backward compatibility)
+      widgetUrl += `?tier=2&proxyUrl=${encodeURIComponent(legacyProxyUrl)}&mode=${mode}`;
+      console.log('[Web Component] TIER 2 legacy mode - using custom proxy:', legacyProxyUrl);
+    } else if (apiKey) {
+      // TIER 1: Public key mode - pass key directly
+      widgetUrl += `?publicKey=${encodeURIComponent(apiKey)}&mode=${mode}`;
+      console.log('[Web Component] TIER 1 mode - using public key');
+    } else {
+      // No valid configuration found
+      this.renderError('Widget requires either an "api-key" attribute for Tier 1 security, or no api-key for Tier 2 security (proxy mode). For Tier 2, ensure you have implemented the proxy at /api/uservibes-proxy.');
+      return;
+    }
+
+    const styles = `
+      <style>
+        :host {
+          display: block;
+          width: 100%;
+        }
+        iframe {
+          width: 100%;
+          height: ${height};
+          border: none;
+          border-radius: 8px;
+          overflow: hidden;
+        }
+        .error {
+          padding: 2rem;
+          text-align: center;
+          border: 1px solid #ef4444;
+          border-radius: 8px;
+          background: #fef2f2;
+          color: #991b1b;
+        }
+      </style>
+    `;
+
+    const iframe = `
+      <iframe
+        src="${widgetUrl}"
+        title="${project} Feature Requests"
+        loading="lazy"
+        allow="clipboard-write"
+      ></iframe>
+    `;
+
+    if (this.shadowRoot) {
+      this.shadowRoot.innerHTML = styles + iframe;
+      this.iframe = this.shadowRoot.querySelector('iframe');
+
+      // Listen for messages from iframe (for height adjustment)
+      this.setupMessageListener();
+    }
+  }
+
+  private renderError(message: string) {
+    const html = `
+      <style>
+        .error {
+          padding: 2rem;
+          text-align: center;
+          border: 1px solid #ef4444;
+          border-radius: 8px;
+          background: #fef2f2;
+          color: #991b1b;
+        }
+      </style>
+      <div class="error">
+        <strong>Widget Error:</strong> ${message}
+      </div>
+    `;
+
+    if (this.shadowRoot) {
+      this.shadowRoot.innerHTML = html;
+    }
+  }
+
+  private setupMessageListener() {
+    window.addEventListener('message', (event) => {
+      // Verify origin for security
+      if (event.origin !== this.baseUrl) {
+        return;
+      }
+
+      // Handle height updates from iframe
+      if (event.data.type === 'USERVIBES_HEIGHT_UPDATE' && this.iframe) {
+        this.iframe.style.height = `${event.data.height}px`;
+      }
+
+      // Dispatch custom events for parent page
+      if (event.data.type === 'USERVIBES_REQUEST_SUBMITTED') {
+        this.dispatchEvent(
+          new CustomEvent('request-submitted', {
+            detail: event.data.payload,
+          })
+        );
+      }
+
+      if (event.data.type === 'USERVIBES_VOTE_ADDED') {
+        this.dispatchEvent(
+          new CustomEvent('vote-added', {
+            detail: event.data.payload,
+          })
+        );
+      }
+    });
+  }
+}
+
+// Register the custom element
+if (typeof window !== 'undefined' && !customElements.get('uservibes-widget')) {
+  customElements.define('uservibes-widget', UserVibesWidget);
+}
+
+export default UserVibesWidget;