webhanger 1.0.8 → 1.1.0

package/README.md

@@ -1,34 +1,32 @@
 # WebHanger
 
-> **Component-as-a-Service (CaaS)** — Bundle once. Encrypt with AES-256. Deliver via edge CDN. Load anywhere with zero code.
+> **Component-as-a-Service (CaaS)** — Bundle once. AES-256 encrypt. Deploy to edge CDN. Load anywhere with zero code.
 
-WebHanger is a secure, edge-delivered component distribution platform. Think of it as npm for UI components — but instead of installing packages, you deploy encrypted components to a CDN and load them into any website with a single HTML tag.
+WebHanger is a secure, edge-delivered component distribution platform. Deploy encrypted UI components to a CDN and load them into any website or framework with a single tag — no tokens in HTML, no exposed secrets, no configuration.
 
 ---
 
+
 ## Packages
 
 | Package | Install | Description |
 |---|---|---|
 | `webhanger` | `npm install -g webhanger` | CLI + Node.js library |
-| `webhanger-front` | `npm install webhanger-front` | Browser SDK |
+| `webhanger-front` | `npm install webhanger-front` | Browser + ESM SDK |
+| `webhanger-admin` | `npm install webhanger-admin` | Admin SDK + dashboard |
+| `webhanger-auth` | `npm install webhanger-auth` | OAuth authentication SDK |
 
 ---
 
 ## Quick Start
 
 ```bash
-# 1. Install CLI
 npm install -g webhanger
-
-# 2. Setup your project (provisions S3 + CloudFront automatically)
 wh init
-
-# 3. Deploy all components, build site, zip for upload — one command
-wh ship ./components ./docs 1.0.0 ./dist
+wh ship ./components ./site 1.0.0 ./dist
 ```
 
-Load in any website — zero JS required:
+Load in any HTML:
 
 ```html
 <script src="https://unpkg.com/webhanger-front@latest/browser.min.js"></script>
@@ -36,7 +34,17 @@ Load in any website — zero JS required:
 
 <wh-component name="navbar"></wh-component>
 <wh-component name="hero"></wh-component>
-<wh-component name="footer"></wh-component>
+<wh-component name="footer" sandbox></wh-component>
+```
+
+Load in Next.js / React / Vite:
+
+```js
+import { load } from "webhanger-front";
+
+const manifest = await fetch("/wh-manifest.json").then(r => r.json());
+const c = manifest.components["navbar"];
+await load(c.urls || c.url, manifest.pid, c.token, c.expires, "#nav-mount");
 ```
 
 ---
@@ -44,177 +52,105 @@ Load in any website — zero JS required:
 ## CLI Reference
 
 ### `wh init`
+Interactive setup. Provisions S3 bucket + CloudFront automatically. Supports Firebase, Supabase, MongoDB. Optional Cloudflare Edge Worker setup.
 
-Interactive project setup. Provisions infrastructure automatically.
+### `wh dev` ⭐ Development server
+Local dev server with hot reload, live preview, and manifest auto-refresh.
 
 ```bash
-wh init
+wh dev ./components 4242
 ```
 
-Prompts:
-- Project name
-- Storage provider: `s3` | `r2` | `minio` | `local`
-- Database provider: `firebase` | `supabase` | `mongodb`
-- Credentials
-
-For **S3**: automatically creates the bucket, configures CORS + versioning, spins up a CloudFront distribution. No AWS Console needed.
-
-Optional: setup Cloudflare Edge Worker for token validation + geo routing at the edge.
-
-Generates `webhanger.config.json`.
-
----
-
-### `wh ship` ⭐ The main command
-
-Deploy + build + zip in one shot.
+Edit any component file → auto-deploys in 300ms → browser hot-reloads. Open `http://localhost:4242` for live preview with a dev status bar at the bottom.
 
 ```bash
-wh ship <components-dir> <site-dir> [version] [out-dir]
+# Custom port + manifest output
+wh dev ./components 3000 ./public/wh-manifest.json
 ```
 
+### `wh ship` ⭐
+Deploy + build + zip in one shot.
 ```bash
-wh ship ./components ./docs 1.0.0 ./dist
+wh ship ./components ./site 1.0.0 ./dist
 ```
-
-What it does:
-1. Deploys all components (bundle → AES encrypt → upload → sign → register)
+1. Deploys all components (bundle → AES-256 encrypt → upload → HMAC sign → register)
 2. Resolves dependency graph
-3. Writes `wh-manifest.json` (no sensitive data in HTML)
-4. Production builds the site (minify HTML, inline CSS/JS)
-5. Zips output for direct upload
-
-```
-🚀 [1/4] Deploying components...
-  navbar@1.0.0...    ✅
-  hero@1.0.0...      ✅
-
-🔍 [2/4] Resolving dependency graph...
-
-🏗️  [3/4] Building ./docs → ./dist...
-  index.html         4.2 kB
-
-📦 [4/4] Zipping ./dist...
-
-✅ Ship complete!
-  Deploy zip: ./deploy.zip (12.4 kB)
-```
-
-Upload `deploy.zip` to Netlify, S3, cPanel, or any static host.
-
----
+3. Writes `wh-manifest.json`
+4. Production builds the site
+5. Zips for upload
 
 ### `wh deploy`
-
-Deploy a single component.
-
 ```bash
-wh deploy <component-dir> <name> <version>
 wh deploy ./components/navbar navbar 1.0.0
 ```
 
-Prompts for token (auto-generate or custom) and expiry (never or seconds).
-
----
-
 ### `wh graph-deploy`
-
-Deploy all components in a directory and resolve the dependency graph.
-
 ```bash
-wh graph-deploy <components-dir> [version] [out-dir]
 wh graph-deploy ./components 1.0.0 ./output
 ```
 
----
+### `wh atomize`
+Split a single HTML page into CDN-powered components.
+```bash
+wh atomize ./docs/index.html ./atomized 1.0.0
+```
 
 ### `wh build`
-
-Production build — minifies HTML, inlines local CSS/JS.
-
+Production build — minifies HTML, extracts CSS/JS to hashed files.
 ```bash
-wh build <src-dir> [out-dir]
-wh build ./docs ./dist
+wh build ./site ./dist
 ```
 
----
-
 ### `wh zip`
-
-Zip a directory for deployment.
-
 ```bash
-wh zip <src-dir> [out-file]
 wh zip ./dist ./deploy.zip
 ```
 
----
-
 ### `wh analyze`
-
-Detect framework, styling approach, and CDN dependencies automatically.
-
 ```bash
 wh analyze ./components/navbar
 ```
 
-```
-🔍 Component Analysis
-
-Framework : vanilla
-Styling   : tailwind
-Imports   : gsap, axios
-CDN Assets:
-  [script] https://cdn.tailwindcss.com
-  [script] https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js
-```
-
----
-
 ### `wh convert`
-
-Convert a vanilla HTML/CSS/JS component to any framework.
-
 ```bash
-wh convert <dir> <name> <target> [out-dir]
 wh convert ./components/navbar navbar react ./output
+# targets: react | vue | svelte | next | angular | astro
 ```
 
-Supported targets: `react` `vue` `svelte` `next` `angular` `astro`
-
----
+### `wh breakdown`
+Extract embedded CSS/JS from a single HTML file.
+```bash
+wh breakdown ./components/navbar
+```
 
 ### `wh access`
-
-Role-based access control for teams.
-
 ```bash
-wh access grant          # generate API key with role
-wh access revoke <key>   # revoke a key
-wh access list           # list all keys
+wh access grant
+wh access revoke <key>
+wh access list
 ```
 
-Roles:
-
-| Role | deploy | read | delete | manage_access |
-|---|---|---|---|---|
-| owner | ✅ | ✅ | ✅ | ✅ |
-| admin | ✅ | ✅ | ✅ | ✅ |
-| deployer | ✅ | ✅ | ❌ | ❌ |
-| viewer | ❌ | ✅ | ❌ | ❌ |
-
----
-
 ### `wh edge-init`
-
-Setup Cloudflare Edge Worker for production-grade delivery.
-
 ```bash
 wh edge-init
-# then:
 cd edge && wrangler deploy
 ```
 
+### `wh auth init`
+Interactive OAuth setup — Google, GitHub, Facebook.
+```bash
+wh auth init
+```
+Prompts for providers, base URL, client IDs/secrets. Generates `wh-auth.config.json` with callback URLs.
+
+### `wh auth serve`
+Start the OAuth callback server.
+```bash
+wh auth serve
+wh auth serve 3001   # custom port
+```
+Handles OAuth redirects, token exchange, JWT issuance.
+
 ---
 
 ## Component Structure
@@ -222,216 +158,546 @@ cd edge && wrangler deploy
 ```
 components/
   navbar/
-    index.html              ← markup
-    style.css               ← styles
-    script.js               ← behaviour
-    webhanger.component.json ← assets + dependencies
+    index.html
+    style.css
+    script.js
+    webhanger.component.json
 ```
 
 ### `webhanger.component.json`
-
 ```json
 {
   "assets": [
-    { "type": "script", "url": "https://cdn.tailwindcss.com" },
-    { "type": "script", "url": "https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js" }
+    { "type": "script", "url": "https://cdn.tailwindcss.com" }
   ],
-  "dependencies": ["navbar@1.0.0", "chart@2.0.0"]
+  "dependencies": ["chart@1.0.0"],
+  "props": {
+    "brand":   { "type": "string", "default": "MyApp" },
+    "ctaText": { "type": "string", "default": "Get Started" },
+    "ctaHref": { "type": "string", "default": "/signup" }
+  }
 }
 ```
 
-CDN assets are auto-detected by `wh analyze` and merged automatically on deploy.
+---
+
+## Component Props System
+
+Pass dynamic data into components via HTML attributes — no redeployment needed.
+
+### In your component HTML, use `{{wh.propName}}` placeholders:
+```html
+<!-- index.html -->
+<nav>
+  <span class="brand">{{wh.brand}}</span>
+  <a href="{{wh.ctaHref}}" class="cta">{{wh.ctaText}}</a>
+</nav>
+```
+
+### Pass props via attributes:
+```html
+<wh-component
+  name="navbar"
+  wh-brand="Acme Corp"
+  wh-cta-text="Sign Up Free"
+  wh-cta-href="/register">
+</wh-component>
+```
+
+### Or programmatically:
+```js
+await load(url, pid, token, 0, "#mount", null, [], {
+  props: {
+    brand: "Acme Corp",
+    ctaText: "Sign Up Free",
+    ctaHref: "/register"
+  }
+});
+```
+
+Props are resolved **after decryption** — the encrypted payload on CDN contains `{{wh.brand}}` literally. The SDK substitutes values in memory before DOM injection. Defaults from `webhanger.component.json` are used when no prop is passed.
 
 ---
 
-## Dependency Graph
+## Security
 
-npm-like dependency resolution for UI components.
+### AES-256-GCM Encryption
+```
+Key     = SHA-256(projectId + salt)
+Payload = iv:tag:ciphertext  (base64)
+Salts   = "::html" | "::css" | "::js"
+```
 
+### HMAC-SHA256 Signed URLs
 ```
-dashboard@1.0.0
-  ├── navbar@1.0.0
-  └── statsbar@1.0.0
-        └── chart@1.0.0
+token = HMAC-SHA256(projectId:path:expires, secretKey)
 ```
 
-- Depth-first resolution
-- Circular dependency detection with full chain error
-- Deps load before parent component
-- Stored in Firestore per project
+### Integrity Check
+SHA-256 hash verified after decryption — detects tampering.
 
-```bash
-wh graph-deploy ./components 1.0.0 ./output
+### Domain Restriction
+```js
+load(url, pid, token, 0, "[data-wh]", null, [], {
+    allowedDomains: ["mysite.com"]
+});
 ```
 
-Programmatic:
+### Manifest-based Delivery
+Tokens, projectId, CDN URLs never in HTML. Fetched at runtime from `wh-manifest.json`.
+
+---
+
+## Dependency Graph
+
+```
+dashboard@1.0.0
+  ├── navbar@1.0.0
+  └── statsbar@1.0.0
+        └── chart@1.0.0
+```
 
 ```js
 import { resolveGraph } from "webhanger";
 const graph = await resolveGraph(config.db, projectId, "dashboard", "1.0.0");
-// Returns: [chart, navbar, statsbar, dashboard] — deps first
+// Returns: [chart, navbar, statsbar, dashboard]
 ```
 
 ---
 
-## Security
+## Multi-CDN Failover
 
-### AES-256-GCM Encryption
+```json
+{
+  "cdn": {
+    "url": "https://primary.cloudfront.net",
+    "fallbacks": ["https://fallback.r2.dev"]
+  }
+}
+```
+
+---
+
+## Edge Worker (Cloudflare Workers)
+
+- HMAC token validation at edge
+- Version resolution (`latest` → `1.2.0`)
+- Geo-based routing
+- Rate limiting (100 req/min per IP)
 
-Every component chunk (HTML/CSS/JS) is encrypted before upload.
+---
+
+## Edge Personalization
+
+Serve different component variants to different users based on rules — country, device, role, A/B test, subscription plan — all resolved client-side or at the Cloudflare edge.
+
+### Setup
+
+```bash
+# Scaffold rules config
+wh personalize init
 
+# Test rule resolution (slot, config, country, device, role)
+wh personalize test ./wh-personalization.json IN mobile premium
+# Output:
+# Context: country=IN device=mobile role=premium
+# Resolved: hero → hero-india  (first matching rule: country=IN)
 ```
-Key     = SHA-256(projectId + salt)
-Payload = iv:tag:ciphertext  (base64)
-Salts   = "::html" | "::css" | "::js"
+
+### `wh-personalization.json`
+
+> **Key rule:** The slot key (e.g. `"hero"`) **must exactly match** the `name` attribute on `<wh-component name="hero">`. The SDK uses the component name as the slot lookup key.
+
+```json
+{
+  "hero": {
+    "rules": [
+      { "if": { "country": "IN" },          "component": "hero-india"    },
+      { "if": { "country": "US" },          "component": "hero-us"       },
+      { "if": { "device": "mobile" },       "component": "hero-mobile"   },
+      { "if": { "role": "premium" },        "component": "hero-premium"  },
+      { "if": { "abTest": "variant-b" },    "component": "hero-variant-b"},
+      { "if": { "hour": { "min": 9, "max": 17 } }, "component": "hero-business" }
+    ],
+    "default": "hero"
+  },
+  "navbar": {
+    "rules": [
+      { "if": { "role": "admin" },   "component": "navbar-admin"   },
+      { "if": { "plan": "premium" }, "component": "navbar-premium" }
+    ],
+    "default": "navbar"
+  }
+}
 ```
 
-### HMAC-SHA256 Signed URLs
+### Zero-code usage
+
+```html
+<script src="https://unpkg.com/webhanger-front@latest/browser.min.js"></script>
+<script>
+  // Load rules first, then initialize
+  WebHangerFront.loadPersonalization("./wh-personalization.json");
+  WebHangerFront.initialize("./wh-manifest.json");
+</script>
 
+<!-- personalize attribute enables rule resolution -->
+<wh-component name="hero" personalize></wh-component>
+<wh-component name="navbar" personalize></wh-component>
 ```
-token = HMAC-SHA256(projectId:componentPath:expires, secretKey)
+
+### Programmatic
+
+```js
+import { load, loadPersonalization } from "webhanger-front";
+
+await loadPersonalization("./wh-personalization.json");
+
+// Override context for testing
+window._wh_ctx_override = { country: "IN", role: "premium" };
+
+// Component resolves to hero-india (first matching rule)
+await load(manifest.components["hero"].url, pid, token, 0, "#hero");
 ```
 
-### Integrity Check
+### Rule conditions
 
-SHA-256 hash of raw content stored in payload. Verified after decryption — detects tampering.
+| Condition | Source | Example |
+|---|---|---|
+| `country` | `window._wh_ctx_override` or IP (edge) | `"IN"`, `["IN","PK"]` |
+| `device` | User-Agent | `"mobile"`, `"tablet"`, `"desktop"` |
+| `role` | JWT from `webhanger-auth` | `"premium"`, `"admin"` |
+| `abTest` | localStorage bucket (stable per user) | `"variant-a"`, `"variant-b"` |
+| `lang` | `navigator.language` | `"en"`, `"hi"` |
+| `hour` | time of day | `{ "min": 9, "max": 17 }` |
+| `plan` | localStorage `wh_plan` | `"free"`, `"premium"` |
 
-### Domain Restriction
+Rules are evaluated top-to-bottom — first match wins. Falls back to `default` if no rule matches.
+
+### Events
 
 ```js
-WebHangerFront.load(url, pid, token, 0, "[data-wh]", null, [], {
-    allowedDomains: ["mysite.com", "app.io"]
+WebHangerFront.on("personalized", ({ slot, resolved, ctx }) => {
+    console.log(`${slot} → ${resolved} (country: ${ctx.country})`);
 });
 ```
 
-### Token Expiry
+### A/B Testing
+
+Each user is automatically assigned a stable bucket (`variant-a` or `variant-b`) stored in localStorage. 50/50 split by default.
 
 ```js
-// Never expires
-wh.deploy("./navbar", "navbar", "1.0.0");
+// Check current bucket
+console.log(localStorage.getItem("wh_ab_bucket")); // "variant-a" or "variant-b"
+```
+
+### Edge resolution (Cloudflare Workers)
+
+When using `wh edge-init`, the worker resolves personalization server-side using Cloudflare headers — no client-side JS needed:
 
-// Expires in 24 hours
-wh.deploy("./navbar", "navbar", "1.0.0", { expiresInSeconds: 86400 });
+```
+CF-IPCountry: IN  →  worker resolves hero-india  →  serves encrypted component
 ```
 
-### Manifest-based Delivery
+Store rules in KV:
+```bash
+wrangler kv:key put --binding=WH_VERSIONS "personalization:hero" '{"rules":[...],"default":"hero"}'
+```
 
-Tokens, projectId, and CDN URLs never appear in HTML. Fetched at runtime from `wh-manifest.json`.
+### Test it
 
----
+```bash
+node personalization-test/deploy.js
+npx serve personalization-test/site
+```
 
-## Edge Worker (Cloudflare Workers)
+Open `http://localhost:3000` — use the simulator buttons to switch country, device, role, and A/B bucket. Watch the hero component change in real time.
 
-Runs at the edge before S3:
+---
 
-- HMAC token validation
-- Version resolution (`latest` → `1.2.0` from KV)
-- Geo-based routing (India → ap-south-1, Europe → eu-west-1)
-- Rate limiting (100 req/min per IP)
+Drop-in OAuth for any website. Supports Google, GitHub, Facebook. Zero backend code required beyond `wh auth serve`.
+
+### Setup
 
 ```bash
-wh init  # answer yes to edge worker setup
-cd edge && wrangler deploy
+npm install -g webhanger        # CLI
+npm install webhanger-auth      # browser SDK
+
+wh auth init                    # configure providers
+wh auth serve                   # start OAuth server (default port 3001)
 ```
 
-Update `cdn.url` in `webhanger.config.json` to your worker URL — all requests now go through the edge.
+### Zero-code HTML
 
----
+```html
+<script src="https://unpkg.com/webhanger-auth/browser.min.js"></script>
 
-## Multi-CDN Failover
+<!-- Renders a styled OAuth button, handles the full flow -->
+<wh-auth
+  provider="google"
+  on-success="/dashboard?name={{name}}&email={{email}}"
+  on-error="/login?error={{message}}"
+  theme="dark">
+</wh-auth>
+
+<wh-auth provider="github"   on-success="/dashboard"></wh-auth>
+<wh-auth provider="facebook" on-success="/dashboard"></wh-auth>
+```
+
+Available `on-success` template variables: `{{name}}` `{{email}}` `{{avatar}}` `{{provider}}` `{{id}}`
+
+### Programmatic
+
+```js
+// Login
+WHAuth.login("google", {
+    onSuccess: (user) => {
+        console.log(user.email, user.name, user.avatar, user.provider);
+        redirect("/dashboard");
+    },
+    onError: (err) => showError(err.message)
+});
+
+// Check session
+WHAuth.isLoggedIn();  // true/false
+WHAuth.getUser();     // { email, name, avatar, provider, id }
+WHAuth.getToken();    // JWT string
+
+// Logout
+WHAuth.logout();
+
+// Events
+WHAuth.on("success", ({ user, token }) => analytics.track("login", user));
+WHAuth.on("error",   ({ message })     => errorTracker.capture(message));
+WHAuth.on("logout",  ()                => clearSession());
+```
+
+### `wh-auth.config.json` (generated by `wh auth init`)
 
 ```json
 {
-  "cdn": {
-    "url": "https://primary.cloudfront.net",
-    "fallbacks": [
-      "https://fallback.r2.dev",
-      "https://backup.b-cdn.net"
-    ]
+  "baseUrl": "https://myapp.com",
+  "callbackPath": "/auth/callback",
+  "port": 3001,
+  "providers": {
+    "google": {
+      "clientId": "...",
+      "clientSecret": "...",
+      "callbackUrl": "https://myapp.com/auth/callback/google"
+    },
+    "github": {
+      "clientId": "...",
+      "clientSecret": "...",
+      "callbackUrl": "https://myapp.com/auth/callback/github"
+    }
+  },
+  "session": {
+    "secret": "auto-generated",
+    "expiresIn": "7d"
   }
 }
 ```
 
-SDK tries each URL in order. If primary fails, automatically falls back — zero code changes needed.
+### Verify JWT server-side
+
+```js
+import { verifyAuthToken } from "webhanger-auth";
+
+const user = await verifyAuthToken(req.headers.authorization?.split(" ")[1]);
+// { email, name, avatar, provider, id, exp, iat }
+```
+
+### Auth flow
+
+```
+User clicks <wh-auth provider="google">
+  └── popup opens → /auth/google
+        └── redirect to Google OAuth consent
+              └── Google → /auth/callback/google?code=xxx
+                    └── exchange code → fetch profile
+                          └── issue JWT
+                                └── postMessage to opener
+                                      └── WHAuth.on("success") fires
+                                            └── redirect to on-success URL
+```
 
 ---
 
-## Browser SDK
+A local web UI + SDK for managing deployed components.
+
+```bash
+npm install webhanger-admin
+
+# Start dashboard
+npx wh-admin ./webhanger.config.json 5000
+```
+
+Open `http://localhost:5000`
+
+Or use programmatically:
+
+```js
+import { WebHangerAdmin } from "webhanger-admin";
 
-### Zero-code (recommended)
+const admin = new WebHangerAdmin("./webhanger.config.json");
 
+const components = await admin.listComponents();
+const manifest   = await admin.generateManifest();
+await admin.saveManifest("./public/wh-manifest.json");
+
+const { apiKey } = await admin.grantAccess("deployer", "CI/CD");
+await admin.resignComponent("navbar", "1.0.0", 86400);
+await admin.deleteComponent("navbar", "1.0.0");
+```
+
+See `webhanger-admin/README.md` for the full API reference.
+
+---
+
+## Browser SDK
+
+### Zero-code Custom Element
 ```html
 <script src="https://unpkg.com/webhanger-front@latest/browser.min.js"></script>
 <script>WebHangerFront.initialize("./wh-manifest.json");</script>
 
-<wh-component name="navbar"></wh-component>
-<wh-component name="hero"></wh-component>
+<wh-component name="navbar" wh-brand="MyApp" wh-cta-text="Start Free"></wh-component>
 <wh-component name="footer" sandbox></wh-component>
 ```
 
-### Manual load
-
+### ESM (Next.js / React / Vite)
 ```js
-WebHangerFront.load(
-    cdnUrl,      // string or array (multi-CDN)
-    projectId,   // decrypt key
-    token,       // HMAC token
-    expires,     // unix timestamp, 0 = never
-    selector,    // CSS selector, default "[data-wh]"
-    onSignal,    // optional signal callback
-    deps,        // optional pre-resolved deps array
-    options      // optional options object
-);
+import { load, use, on, registerSW, clearCache, metrics, gpu } from "webhanger-front";
 ```
 
-### Lifecycle hooks
-
+### Manual load with props
 ```js
-WebHangerFront.load(url, pid, token, 0, "[data-wh]", null, [], {
-    beforeMount: ({ html }) => showSpinner(),
-    afterMount:  ({ target }) => hideSpinner(),
-    onError:     (err) => showFallback(err),
-    sandbox:     true,                          // Shadow DOM isolation
-    allowedDomains: ["mysite.com"]              // domain restriction
-});
+await load(
+    cdnUrl,
+    projectId,
+    token,
+    expires,
+    selector,
+    onSignal,
+    deps,
+    {
+        props: { brand: "MyApp", ctaText: "Get Started" },
+        sandbox: true,
+        allowedDomains: ["mysite.com"],
+        beforeMount: () => showSpinner(),
+        afterMount:  () => hideSpinner(),
+        onError:     (err) => showFallback(err)
+    }
+);
 ```
 
 ### Signal callback
-
 ```js
-WebHangerFront.load(url, pid, token, 0, "[data-wh]", ({ stage, ...detail }) => {
+load(url, pid, token, 0, "[data-wh]", ({ stage, time, source }) => {
     // stages: start → fetching → assets → deps → injecting → done | error
-    console.log(stage, detail.time, detail.source);
 });
 ```
 
 ### Plugin system
-
 ```js
-WebHangerFront.use({
-    install({ on, emit }) {
+use({
+    install({ on }) {
         on("load",   ({ time, source }) => analytics.track("load", { time, source }));
         on("error",  ({ message })      => errorTracker.capture(message));
         on("metric", ({ name, value })  => dashboard.update(name, value));
+        on("gpu",    ({ supported })    => console.log("WebGPU:", supported));
+        on("sw",     ({ scope })        => console.log("SW:", scope));
     }
 });
 ```
 
 ### Observability
+```js
+on("load", ({ time, source }) => console.log(time, source));
+console.log(metrics); // { loads, cacheHits, errors, totalTime }
+```
 
+### WebGPU
 ```js
-WebHangerFront.on("load",   ({ time, source }) => console.log(time, source));
-WebHangerFront.on("metric", ({ name, value })  => console.log(name, value));
+console.log(gpu.supported);
+on("gpu", ({ supported }) => console.log("GPU:", supported));
+```
 
-console.log(WebHangerFront.metrics);
-// { loads: 5, cacheHits: 3, errors: 0, totalTime: 420 }
+### Offline + Service Worker
+```js
+await registerSW("./webhanger.sw.js");
+
+await setOfflinePage(
+    "<h1>Offline</h1><p>Back soon.</p>",
+    "body { background: #030712; color: white; }"
+);
 ```
 
-### Hard flush
+Offline behavior:
+- Online first visit → loads from CDN, caches everything
+- Online repeat visit → loads from SW cache instantly, badge shows
+- Offline with cache → full page works
+- Offline no cache → custom offline page with "⬡ Served by WebHanger" badge
+
+### Smart Cache Invalidation
+
+Only re-fetches from CDN when components actually changed. Checks admin server on every page load — if nothing changed, loads instantly from cache.
+
+```js
+// Instead of initialize(), use smartInitialize()
+WebHangerFront.smartInitialize(
+    "./wh-manifest.json",
+    "http://localhost:5000"  // wh-admin server URL
+);
+```
+
+Flow:
+```
+Page loads
+  └── GET /api/last-updated from admin server (2s timeout)
+        ├── same as localStorage "wh_last_updated"
+        │     └── load all components from cache (instant, 0ms)
+        └── different (components updated since last visit)
+              └── clear component cache
+                    └── reload from CDN
+                          └── update localStorage timestamp
+```
+
+Events:
+```js
+WebHangerFront.on("cache-invalidated", ({ serverTs, cachedTs }) => {
+    console.log("Components updated — reloading from CDN");
+});
+WebHangerFront.on("cache-hit", ({ serverTs }) => {
+    console.log("Up to date — loaded from cache");
+});
+```
+
+If admin server is unreachable (offline, not running), falls back to normal cache behavior silently — zero errors.
+
+Test it:
+```bash
+# 1. Deploy a component
+node smart-cache-test/deploy.js 1.0.0
 
+# 2. Start admin server
+node admin/server.js ./webhanger.config.json 5000
+
+# 3. Serve the test page
+npx serve smart-cache-test/site
+
+# 4. Open http://localhost:3000 — loads from CDN, caches timestamp
+# 5. Refresh — loads from cache instantly (banner: "✓ Up to date")
+# 6. Redeploy with new version
+node smart-cache-test/deploy.js 2.0.0
+# 7. Refresh — cache invalidates, loads fresh (banner: "🔄 Components updated")
+```
+
+See `smart-cache-test/` for the full working demo.
+
+### Hard flush
 ```js
-await WebHangerFront.clearCache();
-// Clears: localStorage, IndexedDB, SW caches, sessionStorage, unregisters SW
+await clearCache();
 ```
 
 ---
@@ -442,9 +708,23 @@ await WebHangerFront.clearCache();
 |---|---|
 | `localStorage` | Components < 50KB |
 | `IndexedDB` | Components ≥ 50KB |
-| Service Worker | Offline fallback |
+| Service Worker | Offline + navigation cache |
+| `wh_last_updated` | Smart cache invalidation timestamp |
 
-**Stale-while-revalidate** — returns cached version instantly, refreshes in background.
+**Stale-while-revalidate** — returns cached instantly, refreshes in background.
+
+**Smart cache invalidation** — `smartInitialize()` checks admin server on every load. Only re-fetches from CDN when components actually changed. Zero CDN requests on cache hits.
+
+---
+
+## Access Control
+
+| Role | deploy | read | delete | manage_access |
+|---|---|---|---|---|
+| owner | ✅ | ✅ | ✅ | ✅ |
+| admin | ✅ | ✅ | ✅ | ✅ |
+| deployer | ✅ | ✅ | ❌ | ❌ |
+| viewer | ❌ | ✅ | ❌ | ❌ |
 
 ---
 
@@ -454,93 +734,105 @@ await WebHangerFront.clearCache();
 import { WebHanger } from "webhanger";
 const wh = new WebHanger();
 
-// Deploy
 const result = await wh.deploy("./components/navbar", "navbar", "1.0.0", {
-    expiresInSeconds: 86400,   // optional
-    token: "custom-token",     // optional
+    expiresInSeconds: 86400,
     dependencies: ["chart@1.0.0"]
 });
-// { cdnUrl, cdnUrls, token, expires, dependencies }
 
-// Resolve
 const comp = await wh.resolve("navbar", "1.0.0");
-
-// Rotate token without redeploying
 await wh.resign("navbar", "1.0.0", { expiresInSeconds: 3600 });
-
-// Delete from storage
 await wh.remove("navbar", "1.0.0");
+```
 
-// Get config
-const config = wh.getConfig();
+---
+
+## Next.js Integration
+
+```bash
+npm install webhanger-front
 ```
 
-### Named exports
+```tsx
+"use client";
+import { useEffect, useRef } from "react";
+import { load } from "webhanger-front";
 
-```js
-import {
-    bundle, encrypt, decrypt, integrityHash,
-    signUrl, verifyToken, generateSecretKey,
-    upload, remove,
-    registerComponent, getComponent,
-    deploy, resolveGraph,
-    convert, analyzeComponent,
-    build,
-    grantAccess, revokeAccess, checkPermission, listAccess, generateApiKey,
-    provisionBucket, provisionCloudFront,
-    loadConfig
-} from "webhanger";
+export default function WebHangerComponent({ name, props = {} }: { name: string; props?: Record<string, string> }) {
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    fetch("/wh-manifest.json")
+      .then(r => r.json())
+      .then(m => {
+        const c = m.components[name];
+        if (!c || !ref.current) return;
+        ref.current.id = `wh-${name}`;
+        load(c.urls || c.url, m.pid, c.token, c.expires, `#wh-${name}`, null, [], { props });
+      });
+  }, [name]);
+
+  return <div ref={ref} />;
+}
+```
+
+```tsx
+// app/page.tsx
+<WebHangerComponent name="navbar" props={{ brand: "MyApp", ctaText: "Sign Up" }} />
 ```
 
 ---
 
+## Examples & Tests
+
+| Folder | What it tests |
+|---|---|
+| `examples/` | Full component deploy + browser SDK demo |
+| `showcase/` | All 4 packages together |
+| `auth-test/` | OAuth login flow (Google, GitHub) |
+| `smart-cache-test/` | Smart cache invalidation demo |
+| `personalization-test/` | Edge personalization — country, device, role, A/B |
+
+```bash
+# Examples
+node examples/deploy.js && npx serve examples/site
+
+# Showcase (all packages)
+node showcase/deploy.js && npx serve showcase/site
+
+# Auth test
+wh auth init && wh auth serve &
+npx serve . # open /auth-test/login.html
+
+# Smart cache test
+node smart-cache-test/deploy.js 1.0.0
+node admin/server.js ./webhanger.config.json 5000 &
+npx serve smart-cache-test/site
+
+# Personalization test
+node personalization-test/deploy.js
+npx serve personalization-test/site
+```
+
+See `examples/EXAMPLE.md` for the full step-by-step guide.
+
+---
+
 ## Storage Providers
 
 | Provider | Notes |
 |---|---|
 | `s3` | AWS S3 — auto-provisions bucket + CloudFront |
 | `r2` | Cloudflare R2 — zero egress fees |
-| `minio` | Self-hosted MinIO — S3-compatible |
-| `local` | Local disk — dev/testing only |
+| `minio` | Self-hosted MinIO |
+| `local` | Local disk — dev only |
 
 ## Database Providers
 
 | Provider | Notes |
 |---|---|
-| `firebase` | Firebase Firestore — free tier, real-time |
-| `supabase` | Supabase Postgres — open source |
-| `mongodb` | MongoDB Atlas — flexible documents |
-
----
-
-## `webhanger.config.json`
-
-```json
-{
-  "project": "my-app",
-  "projectId": "wh_1234567890",
-  "secretKey": "64-char-hex-secret",
-  "webHangerVersion": "1.0.0",
-  "storage": {
-    "provider": "s3",
-    "accessKey": "...",
-    "secretKey": "...",
-    "bucket": "my-bucket",
-    "region": "ap-south-1",
-    "distributionId": "EXXXXX"
-  },
-  "cdn": {
-    "url": "https://primary.cloudfront.net",
-    "fallbacks": ["https://fallback.r2.dev"]
-  },
-  "db": {
-    "provider": "firebase",
-    "serviceAccountPath": "./firebase-service-account.json"
-  }
-}
-```
-
-> Keep this file private. Never commit it. Add to `.gitignore`.
+| `firebase` | Firebase Firestore — free tier |
+| `supabase` | Supabase Postgres |
+| `mongodb` | MongoDB Atlas |
 
 ---
 
@@ -548,47 +840,41 @@ import {
 
 ```
 Developer
-  └── wh ship ./components ./docs
+  └── wh ship ./components ./site
         ├── wh analyze    → detect Tailwind, GSAP, deps
-        ├── wh bundle     → html + css + js → single payload
-        ├── AES-256-GCM   → encrypt each chunk (SHA-256 key)
+        ├── wh breakdown  → extract CSS/JS from single HTML
+        ├── bundle        → html + css + js → single payload
+        ├── props schema  → stored in payload for runtime resolution
+        ├── AES-256-GCM   → encrypt each chunk
         ├── SHA-256 hash  → integrity fingerprint
         ├── S3 upload     → store encrypted payload
         ├── HMAC sign     → project-scoped signed URL
-        ├── Firestore     → register metadata + dep graph
-        ├── wh build      → minify HTML, inline assets
+        ├── DB register   → metadata + dep graph
+        ├── wh build      → minify HTML, extract CSS/JS
         └── wh zip        → deploy.zip ready for upload
 
 Browser
-  └── <wh-component name="navbar">
+  └── <wh-component name="navbar" wh-brand="MyApp">
         ├── fetch wh-manifest.json
         ├── check token expiry
         ├── stale-while-revalidate cache
-        ├── fetch from CloudFront (or Edge Worker)
-        │     └── Edge: validate token + geo route + rate limit
-        ├── multi-CDN failover if primary fails
-        ├── load CDN assets (Tailwind, GSAP, etc.)
-        ├── resolve + load dependency graph
+        ├── fetch from CloudFront / Edge Worker
+        ├── multi-CDN failover
+        ├── load CDN assets
+        ├── resolve dependency graph
         ├── AES-256-GCM decrypt in memory
         ├── SHA-256 integrity verify
+        ├── resolve props ({{wh.brand}} → "MyApp")
         ├── domain restriction check
         ├── inject CSS → HTML → JS (or Shadow DOM)
         ├── fire lifecycle hooks
-        └── emit metrics + plugin events
+        ├── emit metrics + plugin events
+        ├── WebGPU detection
+        └── Service Worker caches for offline
 ```
 
 ---
 
-## Real-World Use Cases
-
-- **Enterprise micro-frontends** — shared UI across 50+ apps, update once
-- **Education platforms** — push UI updates to all school sites instantly
-- **Low-bandwidth regions** — cache once, serve offline via Service Worker
-- **Security platforms** — inject warnings/banners dynamically across sites
-- **White-label SaaS** — per-tenant component customization
-
----
-
 ## License
 
 ISC