webcake-landing-mcp 1.0.81 → 1.0.83

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.0.83",
+    "d": "16/06/2026",
+    "type": "Added",
+    "en": "The server web guide (GET /) now includes a bilingual video guides section with per-app installation walkthrough cards (Claude, Codex, Antigravity);…",
+    "vi": "Web guide của server (GET /) nay có thêm mục video hướng dẫn cài đặt song ngữ với các card theo từng ứng dụng (Claude, Codex, Antigravity); card có…"
+  },
+  {
+    "v": "1.0.82",
+    "d": "16/06/2026",
+    "type": "Added",
+    "en": "render_preview now accepts a tiles parameter: pass tiles:true to receive the page as a stack of top-to-bottom horizontal band images instead of one…",
+    "vi": "render_preview nay nhận tham số tiles: truyền tiles:true để nhận trang dưới dạng stack các ảnh dải ngang từ trên xuống dưới thay vì một ảnh…"
+  },
   {
     "v": "1.0.81",
     "d": "16/06/2026",
@@ -26,19 +40,5 @@
     "type": "Added",
     "en": "The OAuth token store (clients, authorization codes, access and refresh tokens) now uses Postgres when DATABASE_URL, WEBCAKE_POSTGRES_URL, or…",
     "vi": "Kho lưu trữ OAuth token (clients, authorization code, access và refresh token) nay sử dụng Postgres khi DATABASE_URL, WEBCAKE_POSTGRES_URL, hoặc…"
-  },
-  {
-    "v": "1.0.77",
-    "d": "15/06/2026",
-    "type": "Added",
-    "en": "The remote serve transport now implements a spec-conformant OAuth 2.1 Authorization Server (Authorization Code + PKCE S256, Dynamic Client…",
-    "vi": "Transport serve từ xa nay triển khai một OAuth 2.1 Authorization Server chuẩn spec (Authorization Code + PKCE S256, Dynamic Client Registration,…"
-  },
-  {
-    "v": "1.0.76",
-    "d": "15/06/2026",
-    "type": "Added",
-    "en": "validate_page now warns when specials.custom_css sets layout or structural CSS properties (position, top, left, right, bottom, inset, width, height,…",
-    "vi": "validate_page nay cảnh báo khi specials.custom_css đặt các thuộc tính CSS layout hoặc cấu trúc (position, top, left, right, bottom, inset, width,…"
   }
 ]

package/dist/http.js

@@ -21,7 +21,7 @@ import { ICON_SVG, ICON_MIME } from "./branding.js";
 import { guideHtml, ogImageSvg, normalizeLang } from "./web-guide.js";
 import { privacyHtml, termsHtml } from "./legal.js";
 import { searchPexels, resolvePexelsKey } from "./persistence/pexels-client.js";
-import { captureWithPlaywright, isAllowedScreenshotUrl } from "./persistence/screenshot-playwright.js";
+import { captureWithPlaywright, captureTilesWithPlaywright, isAllowedScreenshotUrl } from "./persistence/screenshot-playwright.js";
 import { resolveEnv, ENVIRONMENTS, stripTrailingSlash } from "./persistence/config.js";
 import { buildConnectUrl } from "./auth/login.js";
 import { registerClient, startAuthorize, completeAuthorize, exchangeToken, resolveAccessToken, revokeToken, authServerMetadata, protectedResourceMetadata, } from "./auth/oauth-server.js";
@@ -350,6 +350,23 @@ async function handleRenderScreenshot(req, res) {
         return sendErr(400, { ok: false, error: allow.error });
     const fullPage = sp.get("full_page") !== "false";
     const width = sp.get("width") ? Number(sp.get("width")) : undefined;
+    // Tiles mode: split a tall page into horizontal bands, returned as a JSON array
+    // of base64 images (top→bottom) so the model reads each slice at a readable size.
+    if (sp.get("tiles") === "1" || sp.get("tiles") === "true") {
+        const bandHeight = sp.get("band_height") ? Number(sp.get("band_height")) : undefined;
+        const t = await captureTilesWithPlaywright(target, { width, bandHeight });
+        if (!t.ok)
+            return sendErr(t.reason === "not_installed" ? 503 : 502, { ok: false, error: t.error });
+        res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store", ...cors });
+        return res.end(JSON.stringify({
+            ok: true,
+            mimeType: t.mimeType,
+            page_height: t.pageHeight,
+            width: t.width,
+            truncated: t.truncated,
+            tiles: t.tiles.map((b) => ({ y: b.y, height: b.height, data: b.data.toString("base64") })),
+        }));
+    }
     const r = await captureWithPlaywright(target, { fullPage, width });
     if (!r.ok) {
         // 503 when the engine is absent (caller should fall back / skip), 502 otherwise.

package/dist/mcp/response.js

@@ -18,6 +18,18 @@ export function image(dataBase64, mimeType = "image/png", note) {
     }
     return { content };
 }
+/**
+ * Like `image()` but returns SEVERAL image blocks (e.g. a tall page tiled into
+ * top→bottom bands), optionally followed by a text note. The model sees each band
+ * at a readable size instead of one over-squished image.
+ */
+export function images(items, note) {
+    const content = items.map((it) => ({ type: "image", data: it.dataBase64, mimeType: it.mimeType ?? "image/png" }));
+    if (note !== undefined) {
+        content.push({ type: "text", text: typeof note === "string" ? note : JSON.stringify(note, null, 2) });
+    }
+    return { content };
+}
 /**
  * Directive shipped alongside every non-empty validation-warnings list.
  * Warnings are design defects the customer WILL see (text overlapping the

package/dist/persistence/screenshot-client.js

@@ -132,6 +132,52 @@ export async function captureViaProxy(base, targetUrl, opts, nonce = 0) {
         return { ok: false, status: 0, via: "proxy", error: `network error calling screenshot proxy ${base}: ${e?.message ?? e}` };
     }
 }
+/**
+ * Capture a tall page as horizontal BANDS via the self-hosted Playwright route
+ * (`?tiles=1`) so the model reads each slice at a readable size. Microlink can't
+ * tile, so this REQUIRES a proxy host (RENDER_SCREENSHOT_BASE); without one it
+ * returns not_supported and the caller should fall back to a single full-page shot.
+ * Never throws.
+ */
+export async function captureScreenshotTiles(targetUrl, opts = {}, resolved = {}, nonce = 0) {
+    if (!resolved.proxyBase) {
+        return { ok: false, status: 0, not_supported: true, error: "tiling needs a Playwright host (RENDER_SCREENSHOT_BASE); Microlink can't tile" };
+    }
+    const q = new URLSearchParams();
+    q.set("url", targetUrl + (targetUrl.includes("?") ? "&" : "?") + "_=" + nonce);
+    q.set("tiles", "1");
+    q.set("full_page", "true");
+    if (opts.width && Number.isFinite(opts.width))
+        q.set("width", String(Math.round(opts.width)));
+    if (opts.bandHeight && Number.isFinite(opts.bandHeight))
+        q.set("band_height", String(Math.round(opts.bandHeight)));
+    const url = `${resolved.proxyBase}${SCREENSHOT_PROXY_PATH}?${q.toString()}`;
+    try {
+        const res = await fetch(url, { method: "GET", headers: { Accept: "application/json" }, signal: AbortSignal.timeout(SCREENSHOT_TIMEOUT_MS) });
+        const ct = (res.headers.get("content-type") ?? "").toLowerCase();
+        if (res.ok && ct.includes("application/json")) {
+            const j = await res.json();
+            return {
+                ok: true,
+                status: res.status,
+                mimeType: j.mimeType,
+                pageHeight: j.page_height,
+                width: j.width,
+                truncated: j.truncated === true,
+                tiles: (j.tiles ?? []).map((t) => ({ y: t.y, height: t.height, dataBase64: t.data })),
+                via: "proxy",
+            };
+        }
+        const body = (await res.text()).slice(0, 300);
+        return { ok: false, status: res.status, quota_exhausted: res.status === 429, error: `tiles proxy returned HTTP ${res.status}${body ? `: ${body}` : ""}` };
+    }
+    catch (e) {
+        if (e?.name === "TimeoutError" || e?.name === "AbortError") {
+            return { ok: false, status: 0, error: `tiles request timed out after ${SCREENSHOT_TIMEOUT_MS}ms` };
+        }
+        return { ok: false, status: 0, error: `network error calling tiles proxy ${resolved.proxyBase}: ${e?.message ?? e}` };
+    }
+}
 /**
  * Capture a screenshot with AUTOMATIC FALLOVER between the two engines:
  *   - Microlink direct (free, zero-config) and

package/dist/persistence/screenshot-playwright.js

@@ -79,8 +79,18 @@ function outputOpts() {
     const scale = Number.isFinite(s) && s > 0 && s <= 2 ? s : 1;
     return { type, quality, scale };
 }
-/** Screenshot a URL with Playwright. Never throws. */
-export async function captureWithPlaywright(url, opts = {}) {
+/** Default band height (CSS px) for tiling a tall page; env-tunable. */
+function resolveBandHeight() {
+    const b = parseInt(process.env.RENDER_SCREENSHOT_BAND_HEIGHT ?? "", 10);
+    return Number.isFinite(b) && b >= 200 ? b : 1400;
+}
+/**
+ * Run `fn` against a fresh browser context (viewport width + deviceScaleFactor),
+ * with a single self-heal retry if the cached browser died (crash, or a system
+ * Chrome that closed). Always closes the context. Never throws — the shared
+ * lifecycle for both single-shot and tiled capture.
+ */
+async function withContext(width, scale, fn) {
     const pw = await loadPlaywright();
     if (!pw) {
         return {
@@ -89,13 +99,10 @@ export async function captureWithPlaywright(url, opts = {}) {
             error: "playwright is not installed on this host (run: npm i playwright && npx playwright install chromium)",
         };
     }
-    // One shot, with a single self-heal retry: if the cached browser died (crash,
-    // or a system Chrome that closed), drop it and relaunch once.
     for (let attempt = 0; attempt < 2; attempt++) {
         let browser = await getBrowser();
         if (!browser)
             return { ok: false, error: "failed to launch headless chromium (check CHROME_BIN / playwright install)" };
-        // If the cached handle is already disconnected, force a relaunch.
         if (typeof browser.isConnected === "function" && !browser.isConnected()) {
             browserPromise = null;
             browser = await getBrowser();
@@ -104,24 +111,12 @@ export async function captureWithPlaywright(url, opts = {}) {
         }
         let ctx;
         try {
-            const out = outputOpts();
-            ctx = await browser.newContext({
-                viewport: { width: opts.width && Number.isFinite(opts.width) ? Math.round(opts.width) : 1280, height: 900 },
-                deviceScaleFactor: out.scale,
-            });
-            const page = await ctx.newPage();
-            await page.goto(url, { waitUntil: "load", timeout: 30_000 });
-            await page.waitForTimeout(1200); // let webfonts/lazy images settle
-            const shot = await page.screenshot({
-                fullPage: opts.fullPage !== false,
-                type: out.type,
-                ...(out.type === "jpeg" ? { quality: out.quality } : {}),
-            });
-            return { ok: true, data: Buffer.from(shot), mimeType: out.type === "png" ? "image/png" : "image/jpeg" };
+            ctx = await browser.newContext({ viewport: { width, height: 900 }, deviceScaleFactor: scale });
+            const value = await fn(ctx);
+            return { ok: true, value };
         }
         catch (e) {
             const msg = String(e?.message ?? e);
-            // Browser-died errors → reset and retry once; other errors → fail now.
             const dead = /closed|disconnected|crash|Target page, context or browser/i.test(msg);
             if (dead && attempt === 0) {
                 browserPromise = null;
@@ -136,6 +131,73 @@ export async function captureWithPlaywright(url, opts = {}) {
     }
     return { ok: false, error: "playwright capture failed after retry" };
 }
+/** Load a page in `ctx`, wait for it to settle, return the page handle. */
+async function openSettledPage(ctx, url) {
+    const page = await ctx.newPage();
+    await page.goto(url, { waitUntil: "load", timeout: 30_000 });
+    await page.waitForTimeout(1200); // let webfonts/lazy images settle
+    return page;
+}
+/** Screenshot a URL with Playwright (one image — full page or viewport). Never throws. */
+export async function captureWithPlaywright(url, opts = {}) {
+    const out = outputOpts();
+    const width = opts.width && Number.isFinite(opts.width) ? Math.round(opts.width) : 1280;
+    const r = await withContext(width, out.scale, async (ctx) => {
+        const page = await openSettledPage(ctx, url);
+        return Buffer.from(await page.screenshot({
+            fullPage: opts.fullPage !== false,
+            type: out.type,
+            ...(out.type === "jpeg" ? { quality: out.quality } : {}),
+        }));
+    });
+    if (!r.ok)
+        return r;
+    return { ok: true, data: r.value, mimeType: out.type === "png" ? "image/png" : "image/jpeg" };
+}
+/**
+ * Capture a tall page as a STACK of horizontal bands (top→bottom) via Playwright
+ * `clip` — so the model sees each slice at a readable aspect ratio instead of one
+ * giant image squished (and blurred) to the vision input's long-edge cap. No image
+ * library needed: each band is its own screenshot. Bands are capped at `maxTiles`
+ * (truncated:true when the page is taller than that).
+ */
+export async function captureTilesWithPlaywright(url, opts = {}) {
+    const out = outputOpts();
+    const width = opts.width && Number.isFinite(opts.width) ? Math.round(opts.width) : 1280;
+    const bandH = opts.bandHeight && opts.bandHeight >= 200 ? Math.round(opts.bandHeight) : resolveBandHeight();
+    const maxTiles = opts.maxTiles && opts.maxTiles > 0 ? Math.round(opts.maxTiles) : 8;
+    const r = await withContext(width, out.scale, async (ctx) => {
+        const page = await openSettledPage(ctx, url);
+        // String form so tsc doesn't type-check `document` against the Node libs.
+        const pageHeight = Math.ceil(Number(await page.evaluate("Math.max(document.documentElement.scrollHeight, document.body.scrollHeight)")) || 0);
+        const total = Math.max(1, Math.ceil(pageHeight / bandH));
+        const n = Math.min(total, maxTiles);
+        // `clip` is measured against the VIEWPORT, so grow the viewport to cover the
+        // bands we'll capture before clipping (Chromium caps a single shot at ~16384px).
+        const captureHeight = Math.min(pageHeight, n * bandH, 16000);
+        await page.setViewportSize({ width, height: Math.max(captureHeight, 1) });
+        await page.waitForTimeout(300); // reflow after the resize
+        const tiles = [];
+        for (let i = 0; i < n; i++) {
+            const y = i * bandH;
+            let h = Math.min(bandH, pageHeight - y);
+            if (y + h > captureHeight)
+                h = captureHeight - y; // never clip past the viewport
+            if (h <= 0)
+                break;
+            const shot = await page.screenshot({
+                clip: { x: 0, y, width, height: h },
+                type: out.type,
+                ...(out.type === "jpeg" ? { quality: out.quality } : {}),
+            });
+            tiles.push({ y, height: h, data: Buffer.from(shot) });
+        }
+        return { pageHeight, width, tiles, truncated: total > maxTiles };
+    });
+    if (!r.ok)
+        return r;
+    return { ok: true, mimeType: out.type === "png" ? "image/png" : "image/jpeg", ...r.value };
+}
 // ---------------------------------------------------------------------------
 // SSRF guard — this route fetches an arbitrary `url`, so block private/loopback
 // targets (someone could otherwise screenshot internal services). Pure + exported

package/dist/tools/media.js

@@ -26,9 +26,9 @@ import { z } from "zod";
 import { promises as fs } from "node:fs";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { text, image } from "../mcp/response.js";
+import { text, image, images } from "../mcp/response.js";
 import { searchPexels, searchImagesViaProxy, resolvePexelsKey, resolvePexelsProxyBase, pexelsKeyFromHeaders, } from "../persistence/pexels-client.js";
-import { captureScreenshot, resolveScreenshotProxyBase, screenshotProxyBaseFromHeaders, resolveMicrolinkKey, microlinkKeyFromHeaders, } from "../persistence/screenshot-client.js";
+import { captureScreenshot, captureScreenshotTiles, resolveScreenshotProxyBase, screenshotProxyBaseFromHeaders, resolveMicrolinkKey, microlinkKeyFromHeaders, } from "../persistence/screenshot-client.js";
 import { uploadImageMultipart } from "../persistence/webcake-client.js";
 import { resolveIconSvg } from "../persistence/icon-client.js";
 import { configFromHeaders, ENVIRONMENTS, stripTrailingSlash } from "../persistence/config.js";
@@ -269,12 +269,13 @@ export function registerMediaTools(server, allowLocalFiles = true) {
         });
     });
     // 13c) Render a page/URL to a screenshot the model can SEE --------------------
-    server.tool("render_preview", "Renders a PUBLIC URL to a PNG and returns it as an image so the model can SEE the result and compare it visually to the reference — the fidelity-check step of the clone loop (build → see → patch_page → re-check). Pass `page_id` to shoot a created page's preview (/preview/<id>) or `url` for any public page (e.g. the reference you're cloning). full_page defaults to true (whole scrollable page). AGENT-FIRST: if YOU already have a screenshot/browser capability (a shell + headless browser, or a screenshot tool), screenshot the preview URL YOURSELF instead — it's fresh and unlimited; use this tool only when you cannot. ENGINE: zero-config via Microlink's free tier (rate-limited ~50/day PER IP, so heavy looping can hit HTTP 429 — then this returns ok:false and you should SKIP the visual check that round, not fail); a host can set RENDER_SCREENSHOT_BASE (or the x-render-screenshot-base header) to a keyed proxy, or MICROLINK_API_KEY / x-microlink-key for a higher quota. NOTE: a no-domain preview only renders for ~10 minutes after the last publish — call this promptly after create_page/publish_page, and re-publish before re-checking a stale page.", {
+    server.tool("render_preview", "Renders a PUBLIC URL to a PNG and returns it as an image so the model can SEE the result and compare it visually to the reference — the fidelity-check step of the clone loop (build → see → patch_page → re-check). Pass `page_id` to shoot a created page's preview (/preview/<id>) or `url` for any public page (e.g. the reference you're cloning). full_page defaults to true (whole scrollable page). AGENT-FIRST: if YOU already have a screenshot/browser capability (a shell + headless browser, or a screenshot tool), screenshot the preview URL YOURSELF instead — it's fresh and unlimited; use this tool only when you cannot. ENGINE: zero-config via Microlink's free tier (rate-limited ~50/day PER IP, so heavy looping can hit HTTP 429 — then this returns ok:false and you should SKIP the visual check that round, not fail); a host can set RENDER_SCREENSHOT_BASE (or the x-render-screenshot-base header) to a keyed proxy, or MICROLINK_API_KEY / x-microlink-key for a higher quota. NOTE: a no-domain preview only renders for ~10 minutes after the last publish — call this promptly after create_page/publish_page, and re-publish before re-checking a stale page. TALL PAGES: pass tiles:true to get the page as a STACK of top→bottom band images (each readable at full detail) instead of one full-page image squished small — needs a self-hosted Playwright host (RENDER_SCREENSHOT_BASE); falls back to a single image otherwise.", {
         page_id: z.string().optional().describe("A created page's id — screenshots its /preview/<id> URL (built from the preview base). Provide page_id OR url."),
         url: z.string().optional().describe("Any public http(s) URL to screenshot (e.g. the reference page being cloned). Wins over page_id."),
         full_page: z.boolean().optional().describe("Capture the whole scrollable page (default true) vs just the viewport."),
         width: z.number().int().min(320).max(2560).optional().describe("Viewport width in px (default 1280; use ~960/1200 to match the page canvas, ~420 for mobile)."),
-    }, { title: "Render Preview Screenshot", readOnlyHint: true, openWorldHint: true }, async ({ page_id, url, full_page, width }, extra) => {
+        tiles: z.boolean().optional().describe("Tall pages: return the page as MULTIPLE top→bottom band images (each readable in detail) instead of one squished full-page image. Requires a Playwright host (RENDER_SCREENSHOT_BASE); without one it falls back to a single image."),
+    }, { title: "Render Preview Screenshot", readOnlyHint: true, openWorldHint: true }, async ({ page_id, url, full_page, width, tiles }, extra) => {
         const headers = extra?.requestInfo?.headers;
         let target = url?.trim();
         if (!target && page_id) {
@@ -287,6 +288,26 @@ export function registerMediaTools(server, allowLocalFiles = true) {
             proxyBase: resolveScreenshotProxyBase(screenshotProxyBaseFromHeaders(headers)),
             microlinkKey: resolveMicrolinkKey(microlinkKeyFromHeaders(headers)),
         };
+        // Tiles mode (tall pages): a stack of readable top→bottom bands. Needs a
+        // Playwright host; if none is configured, fall through to a single image.
+        if (tiles === true) {
+            const t = await captureScreenshotTiles(target, { width }, resolved, Date.now());
+            if (t.ok && t.tiles && t.tiles.length) {
+                return images(t.tiles.map((b) => ({ dataBase64: b.dataBase64, mimeType: t.mimeType })), `Rendered ${target} as ${t.tiles.length} band(s) top→bottom (page ${t.pageHeight}px @ ${t.width}px wide${t.truncated ? ", TRUNCATED — page taller than the band cap" : ""}). Read the bands in order as one page. Compare each to the reference: section order, colors, spacing, image placement, text. For each mismatch, patch_page the element by id, re-publish, then re-check.`);
+            }
+            if (!t.not_supported) {
+                // A real failure (quota/network) — report it; don't silently single-shot.
+                return text({
+                    ok: false,
+                    url: target,
+                    status: t.status,
+                    quota_exhausted: t.quota_exhausted ?? false,
+                    error: t.error,
+                    hint: "Tiled screenshot failed. Retry without tiles for a single image, or skip the visual check this round.",
+                });
+            }
+            // not_supported → fall through to a single full-page image below.
+        }
         const r = await captureScreenshot(target, { fullPage: full_page !== false, width }, resolved, Date.now());
         if (!r.ok) {
             return text({

package/dist/web-guide.js

@@ -32,6 +32,16 @@ const INSTALL_ALL_CMD = "npx -y webcake-landing-mcp install --ide all --env prod
 const GITHUB_URL = "https://github.com/vuluu2k/webcake-landing-mcp";
 const NPM_URL = "https://www.npmjs.com/package/webcake-landing-mcp";
 const DOCS_URL = `${GITHUB_URL}#readme`;
+// Per-app video walkthroughs for connecting the MCP, rendered as cards in the
+// guide — each card embeds the YouTube video in a 16:9 iframe. `youtube` is the
+// video ID (privacy-friendly youtube-nocookie embed). Claude has a recorded
+// walkthrough; Codex/Antigravity are placeholders (empty `youtube` → a matching
+// "coming soon" card) until their videos are published — just fill in the ID.
+const VIDEO_GUIDES = [
+    { app: "Claude", icon: "brain", youtube: "NY-YMbSnlOE" },
+    { app: "Codex", icon: "terminal", youtube: "" },
+    { app: "Antigravity", icon: "rocket", youtube: "" },
+];
 export const LANGS = ["vi", "en"];
 export function normalizeLang(input) {
     return input === "en" ? "en" : "vi";
@@ -247,6 +257,10 @@ const T = {
             "<b>Bấm Add</b> (hoặc lưu file) rồi chờ một chút. Khi biểu tượng Webcake chuyển xanh là dùng được.",
         ],
         m2Note: "⚠️ Link có chứa mã đăng nhập riêng của bạn — hãy coi như mật khẩu, đừng chia sẻ cho ai.",
+        videoH2: "Video hướng dẫn cài đặt",
+        videoSub: "Xem video làm theo từng bước cho đúng ứng dụng AI bạn đang dùng.",
+        videoCta: "Xem video",
+        videoSoon: "Sắp có",
         afterH2: "Kết nối xong, bạn chỉ cần nói",
         examples: [
             {
@@ -271,6 +285,14 @@ const T = {
         starBtn: "Tặng sao trên GitHub",
         footGuide: "Hướng dẫn",
         switchLabel: "English",
+        nav: [
+            { href: "#flow", label: "Cách hoạt động" },
+            { href: "#build", label: "Tạo được gì" },
+            { href: "#clone", label: "Copy trang" },
+            { href: "#connect", label: "Kết nối" },
+            { href: "#video", label: "Video" },
+            { href: "#faq", label: "Hỏi đáp" },
+        ],
     },
     en: {
         sub: "Let AI build & edit your Webcake landing pages, just by talking to it",
@@ -378,6 +400,10 @@ const T = {
             "<b>Hit Add</b> (or save the file) and wait a moment. When the Webcake icon turns green, you're good to go.",
         ],
         m2Note: "⚠️ The link contains your personal login code — treat it like a password and never share it.",
+        videoH2: "Video install guides",
+        videoSub: "Follow a step-by-step video for the AI app you use.",
+        videoCta: "Watch video",
+        videoSoon: "Coming soon",
         afterH2: "Once connected, just say",
         examples: [
             {
@@ -402,6 +428,14 @@ const T = {
         starBtn: "Star on GitHub",
         footGuide: "Docs",
         switchLabel: "Tiếng Việt",
+        nav: [
+            { href: "#flow", label: "How it works" },
+            { href: "#build", label: "What you build" },
+            { href: "#clone", label: "Clone a page" },
+            { href: "#connect", label: "Connect" },
+            { href: "#video", label: "Videos" },
+            { href: "#faq", label: "FAQ" },
+        ],
     },
 };
 const CHANGELOG = loadChangelog();
@@ -534,11 +568,11 @@ export function guideHtml(origin, lang = "vi") {
      (the toggle); [data-theme="light"] forces light even on a dark OS. */
   :root{--g:#1DB954;--g7:#178f43;--ink:#11231b;--mut:#5e6d65;--bg:#f5f9f7;--card:#ffffff;
     --line:rgba(16,40,30,.09);--shadow:0 1px 2px rgba(16,40,30,.05),0 6px 20px -12px rgba(16,40,30,.18);--code:#0e1714;
-    --ic-fg:#178f43;--btn-hover:#178f43}
+    --ic-fg:#178f43;--btn-hover:#178f43;--navbg:rgba(245,249,247,.82)}
   @media(prefers-color-scheme:dark){:root:not([data-theme="light"]){--ink:#e8f0ec;--mut:#9aaba2;--bg:#0b110e;--card:#141b17;
-    --line:rgba(255,255,255,.07);--shadow:0 1px 2px rgba(0,0,0,.3),0 8px 24px -14px rgba(0,0,0,.7);--code:#070f0b;--g7:#5ee08a;--ic-fg:#6fe79a;--btn-hover:#21c264}}
+    --line:rgba(255,255,255,.07);--shadow:0 1px 2px rgba(0,0,0,.3),0 8px 24px -14px rgba(0,0,0,.7);--code:#070f0b;--g7:#5ee08a;--ic-fg:#6fe79a;--btn-hover:#21c264;--navbg:rgba(11,17,14,.82)}}
   :root[data-theme="dark"]{--ink:#e8f0ec;--mut:#9aaba2;--bg:#0b110e;--card:#141b17;
-    --line:rgba(255,255,255,.07);--shadow:0 1px 2px rgba(0,0,0,.3),0 8px 24px -14px rgba(0,0,0,.7);--code:#070f0b;--g7:#5ee08a;--ic-fg:#6fe79a;--btn-hover:#21c264}
+    --line:rgba(255,255,255,.07);--shadow:0 1px 2px rgba(0,0,0,.3),0 8px 24px -14px rgba(0,0,0,.7);--code:#070f0b;--g7:#5ee08a;--ic-fg:#6fe79a;--btn-hover:#21c264;--navbg:rgba(11,17,14,.82)}
   *{box-sizing:border-box}
   /* Smooth scrolling only AFTER first load — applied globally it makes the
      browser *animate* scroll-position restoration on reload, which reads as a
@@ -583,7 +617,7 @@ export function guideHtml(origin, lang = "vi") {
     color:var(--g7);background:rgba(29,185,84,.10);border:1px solid var(--line)}
   .dot{width:8px;height:8px;border-radius:50%;background:var(--g);box-shadow:0 0 0 0 rgba(29,185,84,.5);animation:pulse 2s infinite}
   @keyframes pulse{70%{box-shadow:0 0 0 7px rgba(29,185,84,0)}100%{box-shadow:0 0 0 0 rgba(29,185,84,0)}}
-  h2{font-size:1.32rem;margin:46px 0 16px;font-weight:800;letter-spacing:-.01em}
+  h2{font-size:1.32rem;margin:46px 0 16px;font-weight:800;letter-spacing:-.01em;scroll-margin-top:72px}
   .ic{width:42px;height:42px;border-radius:12px;display:grid;place-items:center;flex:0 0 auto;color:var(--ic-fg);
     background:rgba(29,185,84,.11);border:1px solid var(--line);transition:transform .2s ease}
   .ic .i{width:22px;height:22px}
@@ -640,6 +674,49 @@ export function guideHtml(origin, lang = "vi") {
   .btn:hover{transform:translateY(-1px);background:var(--btn-hover)}
   .btn.ghost{background:var(--card);color:var(--ink);border:1px solid var(--line);box-shadow:none}
   .btn.ghost:hover{border-color:var(--g);background:var(--card)}
+  /* Video-guide cards: a 16:9 clickable poster (YouTube thumbnail + play badge)
+     that opens the video in the modal below, or a matching "coming soon"
+     placeholder — so every card lines up to the same height. */
+  .vid-head{display:flex;align-items:center;gap:11px;margin-bottom:14px}
+  .vid-head .ic{margin-bottom:0}
+  .vid-head h3{margin:0;font-size:1.04rem}
+  .vid-play,.vid-soon{aspect-ratio:16/9;border-radius:12px;overflow:hidden;width:100%}
+  .vid-play{position:relative;display:block;padding:0;cursor:pointer;background:#000;
+    border:1px solid var(--line);transition:transform .2s ease,box-shadow .2s ease}
+  .vid-play:hover{transform:translateY(-2px);box-shadow:0 12px 28px -14px rgba(16,40,30,.5)}
+  .vid-play img{position:absolute;inset:0;width:100%;height:100%;object-fit:cover;display:block;border:0}
+  .vid-play::after{content:"";position:absolute;inset:0;background:rgba(0,0,0,.18);transition:background .2s ease}
+  .vid-play:hover::after{background:rgba(0,0,0,.04)}
+  .vid-play .pbtn{position:absolute;top:50%;left:50%;transform:translate(-50%,-50%);width:54px;height:54px;
+    border-radius:50%;background:rgba(29,185,84,.92);display:grid;place-items:center;z-index:1;
+    box-shadow:0 6px 18px -4px rgba(0,0,0,.5);transition:transform .2s ease,background .2s ease}
+  .vid-play:hover .pbtn{transform:translate(-50%,-50%) scale(1.08);background:var(--g)}
+  .vid-play .pbtn svg{width:23px;height:23px;color:#fff;margin-left:3px}
+  .vid-soon{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:8px;
+    color:var(--mut);font-size:.9rem;font-weight:600;background:rgba(29,185,84,.05);border:1px dashed var(--line)}
+  .vid-soon .i{width:24px;height:24px}
+  /* Video modal (lightbox): a single overlay reused for every card's video. */
+  .modal{position:fixed;inset:0;z-index:200;display:none;align-items:center;justify-content:center;
+    padding:24px;background:rgba(4,10,7,.74);backdrop-filter:blur(4px);-webkit-backdrop-filter:blur(4px)}
+  .modal.open{display:flex}
+  .modal-box{position:relative;width:min(960px,100%);aspect-ratio:16/9;background:#000;border-radius:14px;
+    overflow:hidden;box-shadow:0 24px 60px -20px rgba(0,0,0,.8)}
+  .modal-box iframe{position:absolute;inset:0;width:100%;height:100%;border:0}
+  .modal-x{position:absolute;top:-13px;right:-13px;width:38px;height:38px;border-radius:50%;cursor:pointer;
+    background:var(--g);color:#fff;border:2px solid #fff;display:grid;place-items:center;z-index:2;
+    box-shadow:0 4px 14px -2px rgba(0,0,0,.5)}
+  .modal-x svg{width:18px;height:18px}
+  @media(max-width:640px){.modal{padding:14px}.modal-x{top:-11px;right:-11px;width:34px;height:34px}}
+  /* Sticky section nav — pins to the top once you scroll past the hero so the
+     reader can jump to any section; horizontally scrollable on narrow screens. */
+  .nav{position:sticky;top:0;z-index:60;display:flex;gap:6px;align-items:center;overflow-x:auto;
+    margin:18px -20px 6px;padding:9px 20px;background:var(--navbg);border-bottom:1px solid var(--line);
+    backdrop-filter:blur(12px);-webkit-backdrop-filter:blur(12px);scrollbar-width:none}
+  .nav::-webkit-scrollbar{display:none}
+  .nav a{flex:0 0 auto;font-size:.84rem;font-weight:600;color:var(--mut);text-decoration:none;
+    padding:7px 13px;border-radius:999px;white-space:nowrap;transition:color .15s ease,background .15s ease}
+  .nav a:hover{color:var(--g7);background:rgba(29,185,84,.10)}
+  .nav a.active{color:var(--g7);background:rgba(29,185,84,.13)}
   .uses{display:grid;gap:14px;grid-template-columns:1fr 1fr;padding:0;margin:0;list-style:none}
   @media(max-width:640px){.uses{grid-template-columns:1fr}}
   .uses li{display:flex;gap:13px;padding:16px 18px;align-items:flex-start;transition:transform .2s ease,border-color .2s ease,box-shadow .2s ease}
@@ -772,7 +849,11 @@ export function guideHtml(origin, lang = "vi") {
     <a class="btn ghost" href="${GITHUB_URL}">${icon("star")} ${t.ctaStar}</a>
   </div>
 
-  <h2 class="reveal">${t.flowH2}</h2>
+  <nav class="nav" aria-label="${L === "en" ? "Sections" : "Mục lục"}">
+    ${t.nav.map((n) => `<a href="${n.href}">${n.label}</a>`).join("\n    ")}
+  </nav>
+
+  <h2 id="flow" class="reveal">${t.flowH2}</h2>
   <div class="glass flow reveal">
     ${t.flow
         .map((n, i) => `<div class="node"><span class="ic" style="animation-delay:${(i * 0.8).toFixed(1)}s">${icon(n.icon)}</span><b>${n.t}</b><span>${n.s}</span></div>` +
@@ -790,14 +871,14 @@ export function guideHtml(origin, lang = "vi") {
         .join("\n    ")}
   </div>
 
-  <h2 class="reveal">${t.buildH2}</h2>
+  <h2 id="build" class="reveal">${t.buildH2}</h2>
   <ul class="uses">
     ${t.uses
         .map((u) => `<li class="glass reveal">${tile(u.icon)}<div><b>${u.t}</b><span>${u.e}</span></div></li>`)
         .join("\n    ")}
   </ul>
 
-  <h2 class="reveal">${t.cloneH2}</h2>
+  <h2 id="clone" class="reveal">${t.cloneH2}</h2>
   <p class="flow-cap reveal" style="margin-bottom:16px">${t.cloneSub}</p>
   <div class="grid">
     ${t.clone
@@ -826,6 +907,14 @@ export function guideHtml(origin, lang = "vi") {
     <p class="note">${t.m2Note}</p>
   </div>
 
+  <h2 id="video" class="reveal">${t.videoH2}</h2>
+  <p class="flow-cap reveal" style="margin-bottom:16px">${t.videoSub}</p>
+  <div class="grid">
+    ${VIDEO_GUIDES.map((v) => `<div class="glass card vid reveal"><div class="vid-head">${tile(v.icon)}<h3>${v.app}</h3></div>${v.youtube
+        ? `<button type="button" class="vid-play" data-yt="${v.youtube}" data-title="${v.app} — ${t.videoCta}" aria-label="${v.app} — ${t.videoCta}"><img src="https://i.ytimg.com/vi/${v.youtube}/hqdefault.jpg" alt="" loading="lazy"><span class="pbtn"><svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M8 5v14l11-7z"/></svg></span></button>`
+        : `<div class="vid-soon">${icon("clock")}<span>${t.videoSoon}</span></div>`}</div>`).join("\n    ")}
+  </div>
+
   <h2 class="reveal">${t.afterH2}</h2>
   <ul class="feat">
     ${t.examples
@@ -843,7 +932,7 @@ export function guideHtml(origin, lang = "vi") {
   </div>`
         : ""}
 
-  <h2 class="reveal">${t.faqH2}</h2>
+  <h2 id="faq" class="reveal">${t.faqH2}</h2>
   ${faq.map((f) => `<details class="glass reveal"><summary>${f.q}</summary><p>${f.a}</p></details>`).join("\n  ")}
 
   <div class="glass star reveal">
@@ -860,6 +949,13 @@ export function guideHtml(origin, lang = "vi") {
     <a href="${selfPath === "/" ? "/health" : "/health"}">Health</a>
   </footer>
 
+  <div class="modal" id="vmodal" role="dialog" aria-modal="true" aria-label="${t.videoH2}">
+    <div class="modal-box">
+      <button type="button" class="modal-x" id="vclose" aria-label="Close" title="Close"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" aria-hidden="true"><path d="M18 6 6 18"/><path d="m6 6 12 12"/></svg></button>
+      <iframe id="vframe" title="${t.videoH2}" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+    </div>
+  </div>
+
 </div>
 <script>
 (function(){
@@ -916,6 +1012,47 @@ export function guideHtml(origin, lang = "vi") {
   // Enable smooth scrolling only after the browser has restored scroll position
   // on (re)load — applying it globally animates that restore into a jerky scroll.
   window.addEventListener('load',function(){requestAnimationFrame(function(){html.classList.add('smooth');});});
+
+  // Video lightbox — clicking a card poster opens the YouTube embed in a modal.
+  // The iframe src is only set on open (no YouTube network/tracking until the
+  // user clicks) and cleared on close (which stops playback). Esc, the backdrop
+  // and the × button all close it; focus is restored to the trigger on close.
+  var modal=document.getElementById('vmodal'),vframe=document.getElementById('vframe'),
+      vclose=document.getElementById('vclose'),lastFocus=null;
+  function openVideo(id,title){
+    if(!modal||!vframe||!id)return;
+    vframe.src='https://www.youtube-nocookie.com/embed/'+id+'?autoplay=1&rel=0';
+    if(title)vframe.title=title;
+    lastFocus=document.activeElement;
+    modal.classList.add('open');document.body.style.overflow='hidden';
+    if(vclose)vclose.focus();
+  }
+  function closeVideo(){
+    if(!modal||!modal.classList.contains('open'))return;
+    modal.classList.remove('open');vframe.src='';document.body.style.overflow='';
+    if(lastFocus&&lastFocus.focus)lastFocus.focus();
+  }
+  document.querySelectorAll('.vid-play').forEach(function(b){
+    b.addEventListener('click',function(){openVideo(b.getAttribute('data-yt'),b.getAttribute('data-title')||'');});
+  });
+  if(vclose)vclose.addEventListener('click',closeVideo);
+  if(modal)modal.addEventListener('click',function(e){if(e.target===modal)closeVideo();});
+  document.addEventListener('keydown',function(e){if(e.key==='Escape')closeVideo();});
+
+  // Sticky-nav scrollspy — highlight the link for the section currently on screen.
+  var navLinks={};
+  document.querySelectorAll('.nav a').forEach(function(a){navLinks[a.getAttribute('href').slice(1)]=a;});
+  var spySecs=[].slice.call(document.querySelectorAll('h2[id]'));
+  var spyTick=false;
+  function spy(){
+    spyTick=false;var cur=null;
+    spySecs.forEach(function(s){if(s.getBoundingClientRect().top<=96)cur=s.id;});
+    Object.keys(navLinks).forEach(function(id){navLinks[id].classList.toggle('active',id===cur);});
+  }
+  if(spySecs.length&&Object.keys(navLinks).length){
+    window.addEventListener('scroll',function(){if(!spyTick){spyTick=true;requestAnimationFrame(spy);}},{passive:true});
+    spy();
+  }
 })();
 </script>
 </body></html>`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-landing-mcp",
-  "version": "1.0.81",
+  "version": "1.0.83",
   "description": "MCP server exposing Webcake landing-page element schemas + AI usage hints, and persisting LLM-generated page sources to a Webcake backend.",
   "mcpName": "io.github.vuluu2k/webcake-landing-mcp",
   "type": "module",