webhanger 1.0.9 → 1.1.0

package/README.md

@@ -54,6 +54,20 @@ await load(c.urls || c.url, manifest.pid, c.token, c.expires, "#nav-mount");
 ### `wh init`
 Interactive setup. Provisions S3 bucket + CloudFront automatically. Supports Firebase, Supabase, MongoDB. Optional Cloudflare Edge Worker setup.
 
+### `wh dev` ⭐ Development server
+Local dev server with hot reload, live preview, and manifest auto-refresh.
+
+```bash
+wh dev ./components 4242
+```
+
+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
+# Custom port + manifest output
+wh dev ./components 3000 ./public/wh-manifest.json
+```
+
 ### `wh ship` ⭐
 Deploy + build + zip in one shot.
 ```bash
@@ -273,7 +287,133 @@ const graph = await resolveGraph(config.db, projectId, "dashboard", "1.0.0");
 
 ---
 
-## OAuth Authentication (webhanger-auth)
+## 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)
+```
+
+### `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"
+  }
+}
+```
+
+### 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>
+```
+
+### 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");
+```
+
+### Rule conditions
+
+| 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"` |
+
+Rules are evaluated top-to-bottom — first match wins. Falls back to `default` if no rule matches.
+
+### Events
+
+```js
+WebHangerFront.on("personalized", ({ slot, resolved, ctx }) => {
+    console.log(`${slot} → ${resolved} (country: ${ctx.country})`);
+});
+```
+
+### 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
+// 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:
+
+```
+CF-IPCountry: IN  →  worker resolves hero-india  →  serves encrypted component
+```
+
+Store rules in KV:
+```bash
+wrangler kv:key put --binding=WH_VERSIONS "personalization:hero" '{"rules":[...],"default":"hero"}'
+```
+
+### Test it
+
+```bash
+node personalization-test/deploy.js
+npx serve personalization-test/site
+```
+
+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.
+
+---
 
 Drop-in OAuth for any website. Supports Google, GitHub, Facebook. Zero backend code required beyond `wh auth serve`.
 
@@ -650,6 +790,7 @@ export default function WebHangerComponent({ name, props = {} }: { name: string;
 | `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
@@ -666,6 +807,10 @@ npx serve . # open /auth-test/login.html
 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.

package/bin/cli.js

@@ -460,6 +460,29 @@ ${mounts}
         }
         break;
     }
+    case "dev": {
+        const devDir     = args[1] || "./components";
+        const devPort    = parseInt(args[2] || "4242");
+        const devManifest = args[3] || "./wh-manifest.json";
+
+        const loadConfigFn = (await import("../helper/loadConfig.js")).default;
+        const { startDevServer } = await import("../core/devServer.js");
+
+        const config = loadConfigFn();
+
+        console.log(chalk.cyan("\n⚡ wh dev — WebHanger Development Server\n"));
+
+        try {
+            await startDevServer(config, devDir, {
+                port: devPort,
+                manifestOut: devManifest
+            });
+        } catch (err) {
+            console.log(chalk.red(`\n❌ Dev server failed: ${err.message}`));
+            process.exit(1);
+        }
+        break;
+    }
     case "personalize": {
         const { default: fsExtra } = await import("fs-extra");
         const { default: pathMod } = await import("path");
@@ -1102,7 +1125,7 @@ ${mounts}
             console.log(chalk.red("Usage: wh analyze <component-dir>"));
             process.exit(1);
         }
-        const { analyzeComponent } = await import("../helper/analyzer.js");
+        const { analyzeComponent, autoGenerateComponentMeta } = await import("../helper/analyzer.js");
         const result = await analyzeComponent(dir);
         console.log(chalk.cyan("\n🔍 Component Analysis\n"));
         console.log(chalk.white(`Framework : ${result.framework}`));
@@ -1114,12 +1137,26 @@ ${mounts}
         } else {
             console.log(chalk.gray("  none"));
         }
+
+        // Also run autoGenerate to show props
+        const { meta } = await autoGenerateComponentMeta(dir);
+        const propKeys = Object.keys(meta.props || {});
+        if (propKeys.length) {
+            console.log(chalk.white(`\nProps detected ({{wh.*}} placeholders):`));
+            propKeys.forEach(k => {
+                const p = meta.props[k];
+                console.log(chalk.gray(`  ${k.padEnd(20)} default: "${p.default || ""}"`));
+            });
+            console.log(chalk.green(`\n✅ webhanger.component.json updated with ${propKeys.length} props`));
+        }
+        console.log();
         break;
     }
     default:
         console.log(chalk.cyan(BANNER));
         console.log(chalk.white("Commands:"));
         console.log(chalk.gray("  wh init                                              — setup your project"));
+        console.log(chalk.gray("  wh dev [comp-dir] [port] [manifest-out]              — dev server with hot reload + live preview"));
         console.log(chalk.gray("  wh ship <comp-dir> <site-dir> [version] [out-dir]    — deploy + build + zip in one shot"));
         console.log(chalk.gray("  wh deploy <dir> <name> <version>                     — deploy a single component"));
         console.log(chalk.gray("  wh graph-deploy <comp-dir> [version] [out-dir]       — deploy all + resolve dep graph"));

package/core/devServer.js

@@ -0,0 +1,337 @@
+/**
+ * WebHanger Dev Server
+ * - Watches component files for changes
+ * - Auto-deploys on save (bundle → encrypt → upload → register)
+ * - Serves a live preview with hot reload
+ * - Auto-refreshes wh-manifest.json
+ * - Tests dependency graph on every change
+ */
+
+import http from "http";
+import path from "path";
+import fs from "fs-extra";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ─── File watcher (no deps — uses fs.watch) ───────────────────────────────────
+
+function watchDir(dir, onChange) {
+    const watchers = new Map();
+
+    function watchRecursive(d) {
+        if (!fs.existsSync(d)) return;
+        const watcher = fs.watch(d, { recursive: false }, (event, filename) => {
+            if (filename) onChange(path.join(d, filename), event);
+        });
+        watchers.set(d, watcher);
+
+        for (const entry of fs.readdirSync(d)) {
+            const full = path.join(d, entry);
+            if (fs.statSync(full).isDirectory()) watchRecursive(full);
+        }
+    }
+
+    watchRecursive(dir);
+    return () => watchers.forEach(w => w.close());
+}
+
+// ─── SSE broadcaster (for hot reload) ────────────────────────────────────────
+
+function createSSE() {
+    const clients = new Set();
+
+    function addClient(res) {
+        res.writeHead(200, {
+            "Content-Type":  "text/event-stream",
+            "Cache-Control": "no-cache",
+            "Connection":    "keep-alive",
+            "Access-Control-Allow-Origin": "*"
+        });
+        res.write("data: connected\n\n");
+        clients.add(res);
+        res.on("close", () => clients.delete(res));
+    }
+
+    function broadcast(event, data) {
+        const msg = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+        clients.forEach(res => { try { res.write(msg); } catch (_) {} });
+    }
+
+    return { addClient, broadcast, clientCount: () => clients.size };
+}
+
+// ─── Dev server ───────────────────────────────────────────────────────────────
+
+export async function startDevServer(config, componentsDir, options = {}) {
+    const PORT        = options.port || 4242;
+    const manifestOut = options.manifestOut || path.join(process.cwd(), "wh-manifest.json");
+
+    const { deploy } = await import("./registry.js");
+    const { resolveGraph } = await import("./resolver.js");
+
+    const sse = createSSE();
+    const deployQueue = new Map(); // debounce per component
+    const deployedComponents = new Map();
+
+    // ── Scan component folders ────────────────────────────────────────────────
+    async function scanComponents() {
+        const entries = await fs.readdir(componentsDir);
+        const comps = [];
+        for (const entry of entries) {
+            const full = path.join(componentsDir, entry);
+            const stat = await fs.stat(full);
+            if (stat.isDirectory()) comps.push({ name: entry, dir: full });
+        }
+        return comps;
+    }
+
+    // ── Deploy a single component ─────────────────────────────────────────────
+    async function deployComponent(name, dir, version = "dev") {
+        const start = Date.now();
+        try {
+            const result = await deploy(config, dir, name, version);
+            deployedComponents.set(name, result);
+            await refreshManifest();
+
+            const elapsed = Date.now() - start;
+            sse.broadcast("component-updated", {
+                name, version, cdnUrl: result.cdnUrl,
+                time: elapsed, ts: Date.now()
+            });
+
+            return { success: true, name, elapsed };
+        } catch (err) {
+            sse.broadcast("deploy-error", { name, message: err.message });
+            return { success: false, name, error: err.message };
+        }
+    }
+
+    // ── Refresh manifest ──────────────────────────────────────────────────────
+    async function refreshManifest() {
+        const manifest = {
+            pid: config.projectId,
+            components: {}
+        };
+        for (const [name, d] of deployedComponents) {
+            manifest.components[name] = {
+                url:     d.cdnUrl,
+                urls:    d.cdnUrls || [d.cdnUrl],
+                token:   d.token,
+                expires: d.expires
+            };
+        }
+        await fs.writeJson(manifestOut, manifest, { spaces: 2 });
+        sse.broadcast("manifest-updated", { componentCount: deployedComponents.size, ts: Date.now() });
+        return manifest;
+    }
+
+    // ── Test dependency graph ─────────────────────────────────────────────────
+    async function testDependencyGraph(rootName) {
+        try {
+            const graph = await resolveGraph(config.db, config.projectId, rootName, "dev");
+            sse.broadcast("dep-graph", { root: rootName, graph: graph.map(c => `${c.name}@${c.version}`) });
+            return graph;
+        } catch (err) {
+            sse.broadcast("dep-error", { root: rootName, message: err.message });
+            return null;
+        }
+    }
+
+    // ── Watch for file changes ────────────────────────────────────────────────
+    const stopWatching = watchDir(componentsDir, (filePath, event) => {
+        const rel = path.relative(componentsDir, filePath);
+        const compName = rel.split(path.sep)[0];
+        if (!compName) return;
+
+        // Debounce — wait 300ms after last change before deploying
+        if (deployQueue.has(compName)) clearTimeout(deployQueue.get(compName));
+        deployQueue.set(compName, setTimeout(async () => {
+            deployQueue.delete(compName);
+            const compDir = path.join(componentsDir, compName);
+            if (!fs.existsSync(compDir)) return;
+            console.log(`[wh dev] 🔄 ${compName} changed — redeploying...`);
+            const result = await deployComponent(compName, compDir);
+            if (result.success) {
+                console.log(`[wh dev] ✅ ${compName} deployed in ${result.elapsed}ms`);
+            } else {
+                console.log(`[wh dev] ❌ ${compName}: ${result.error}`);
+            }
+        }, 300));
+    });
+
+    // ── HTTP server ───────────────────────────────────────────────────────────
+    const server = http.createServer(async (req, res) => {
+        const url = new URL(req.url, `http://localhost:${PORT}`);
+        const p   = url.pathname;
+
+        // CORS
+        res.setHeader("Access-Control-Allow-Origin", "*");
+
+        // SSE endpoint — browser connects for hot reload
+        if (p === "/__wh_dev__/events") {
+            sse.addClient(res); return;
+        }
+
+        // Status
+        if (p === "/__wh_dev__/status") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                running: true,
+                components: [...deployedComponents.keys()],
+                clients: sse.clientCount(),
+                manifestPath: manifestOut
+            })); return;
+        }
+
+        // Trigger manual redeploy
+        if (p === "/__wh_dev__/redeploy" && req.method === "POST") {
+            const comps = await scanComponents();
+            const results = [];
+            for (const comp of comps) {
+                const r = await deployComponent(comp.name, comp.dir);
+                results.push(r);
+            }
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ results })); return;
+        }
+
+        // Serve preview page
+        if (p === "/" || p === "/index.html") {
+            const manifest = await refreshManifest().catch(() => ({ components: {} }));
+            const mounts = Object.keys(manifest.components)
+                .map(name => `  <wh-component name="${name}"></wh-component>`)
+                .join("\n");
+
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end(previewPage(mounts, PORT)); return;
+        }
+
+        // Serve manifest
+        if (p === "/wh-manifest.json") {
+            if (fs.existsSync(manifestOut)) {
+                const data = await fs.readFile(manifestOut, "utf-8");
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(data);
+            } else {
+                res.writeHead(404); res.end("{}");
+            }
+            return;
+        }
+
+        res.writeHead(404); res.end("Not found");
+    });
+
+    // ── Initial deploy ────────────────────────────────────────────────────────
+    console.log(`[wh dev] 🔍 Scanning ${componentsDir}...`);
+    const comps = await scanComponents();
+    console.log(`[wh dev] Found ${comps.length} components — deploying...\n`);
+
+    for (const comp of comps) {
+        process.stdout.write(`  ${comp.name}... `);
+        const r = await deployComponent(comp.name, comp.dir);
+        console.log(r.success ? `✅ (${r.elapsed}ms)` : `❌ ${r.error}`);
+    }
+
+    server.listen(PORT, () => {
+        console.log(`\n[wh dev] 🚀 Dev server running`);
+        console.log(`  Preview  : http://localhost:${PORT}`);
+        console.log(`  Manifest : http://localhost:${PORT}/wh-manifest.json`);
+        console.log(`  Status   : http://localhost:${PORT}/__wh_dev__/status`);
+        console.log(`\n[wh dev] 👀 Watching ${componentsDir} for changes...\n`);
+    });
+
+    return { server, stopWatching };
+}
+
+// ─── Preview page HTML ────────────────────────────────────────────────────────
+
+function previewPage(mounts, port) {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>wh dev — Live Preview</title>
+  <style>
+    *{margin:0;padding:0;box-sizing:border-box}
+    body{background:#030712;color:#e8eaf0;font-family:system-ui,sans-serif}
+    #wh-dev-bar{
+      position:fixed;bottom:0;left:0;right:0;z-index:9999;
+      background:#0d0e12;border-top:1px solid #1e2028;
+      padding:8px 16px;display:flex;align-items:center;gap:12px;
+      font-family:monospace;font-size:11px;
+    }
+    .dev-dot{width:7px;height:7px;border-radius:50%;background:#4ade80;animation:pulse 2s infinite}
+    @keyframes pulse{0%,100%{opacity:1}50%{opacity:.4}}
+    .dev-status{color:#4ade80;font-weight:600}
+    .dev-log{color:#6b7280;flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+    .dev-reload{background:none;border:1px solid #374151;color:#9ca3af;padding:4px 10px;border-radius:4px;cursor:pointer;font-size:11px;font-family:monospace}
+    .dev-reload:hover{border-color:#6366f1;color:#818cf8}
+  </style>
+</head>
+<body>
+
+${mounts}
+
+<div id="wh-dev-bar">
+  <div class="dev-dot" id="dev-dot"></div>
+  <span class="dev-status" id="dev-status">wh dev</span>
+  <span class="dev-log" id="dev-log">Connected — watching for changes</span>
+  <button class="dev-reload" onclick="location.reload()">↻ Reload</button>
+</div>
+
+<script src="https://unpkg.com/webhanger-front@latest/browser.min.js"></script>
+<script>
+  WebHangerFront.initialize("/wh-manifest.json");
+
+  // ── Hot reload via SSE
+  var es = new EventSource("/__wh_dev__/events");
+  var dot = document.getElementById("dev-dot");
+  var status = document.getElementById("dev-status");
+  var log = document.getElementById("dev-log");
+
+  function setLog(msg, color) {
+    log.textContent = msg;
+    if (color) log.style.color = color;
+  }
+
+  es.addEventListener("component-updated", function(e) {
+    var d = JSON.parse(e.data);
+    dot.style.background = "#fbbf24";
+    setLog("🔄 " + d.name + " updated (" + d.time + "ms) — reloading...", "#fbbf24");
+    setTimeout(function() { location.reload(); }, 500);
+  });
+
+  es.addEventListener("deploy-error", function(e) {
+    var d = JSON.parse(e.data);
+    dot.style.background = "#f87171";
+    setLog("❌ " + d.name + ": " + d.message, "#f87171");
+  });
+
+  es.addEventListener("manifest-updated", function(e) {
+    var d = JSON.parse(e.data);
+    setLog("📋 Manifest updated — " + d.componentCount + " components", "#60a5fa");
+  });
+
+  es.addEventListener("dep-graph", function(e) {
+    var d = JSON.parse(e.data);
+    setLog("🔗 Dep graph: " + d.graph.join(" → "), "#c084fc");
+  });
+
+  es.onopen = function() {
+    dot.style.background = "#4ade80";
+    status.textContent = "wh dev";
+    setLog("Connected — watching for changes", "#4ade80");
+  };
+
+  es.onerror = function() {
+    dot.style.background = "#f87171";
+    status.textContent = "disconnected";
+    setLog("Dev server disconnected — retrying...", "#f87171");
+  };
+</script>
+
+</body>
+</html>`;
+}

package/helper/analyzer.js

@@ -162,21 +162,48 @@ export async function analyzeComponent(componentDir) {
 
 /**
  * Auto-generates webhanger.component.json if it doesn't exist.
- * If it exists, merges new assets without overwriting manual ones.
+ * If it exists, merges new assets + props without overwriting manual ones.
  */
 export async function autoGenerateComponentMeta(componentDir) {
     const metaPath = path.join(componentDir, "webhanger.component.json");
     const analysis = await analyzeComponent(componentDir);
 
-    let existing = { assets: [] };
+    // Extract {{wh.propName}} placeholders from HTML
+    const htmlPath = path.join(componentDir, "index.html");
+    const props = {};
+    if (await fs.pathExists(htmlPath)) {
+        const html = await fs.readFile(htmlPath, "utf-8");
+        const matches = [...html.matchAll(/\{\{wh\.([a-zA-Z0-9_]+)\}\}/g)];
+        for (const m of matches) {
+            const propName = m[1];
+            if (!props[propName]) {
+                props[propName] = { type: "string", default: "" };
+            }
+        }
+    }
+
+    let existing = { assets: [], dependencies: [], props: {} };
     if (await fs.pathExists(metaPath)) {
         existing = await fs.readJson(metaPath);
+        if (!existing.props) existing.props = {};
     }
 
-    // Merge — don't duplicate URLs
-    const existingUrls = new Set(existing.assets.map(a => a.url));
+    // Merge assets — don't duplicate URLs
+    const existingUrls = new Set((existing.assets || []).map(a => a.url));
     const newAssets = analysis.assets.filter(a => !existingUrls.has(a.url));
-    const merged = { ...existing, assets: [...existing.assets, ...newAssets] };
+
+    // Merge props — don't overwrite existing defaults
+    const mergedProps = { ...props };
+    for (const [key, val] of Object.entries(existing.props || {})) {
+        mergedProps[key] = val; // existing props take priority
+    }
+
+    const merged = {
+        ...existing,
+        assets: [...(existing.assets || []), ...newAssets],
+        dependencies: existing.dependencies || [],
+        props: mergedProps
+    };
 
     await fs.writeJson(metaPath, merged, { spaces: 2 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webhanger",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "description": "Component-as-a-Service platform — bundle, sign, and deliver UI components via edge CDN",
   "type": "module",
   "main": "index.js",