docs: add cross-site announcement banner

[jdx]

Summary

• Adds docs/.vitepress/theme/banner.ts + banner.css \u2014 fetches banner config from https://jdx.dev/banner.json and renders a dismissible announcement bar at the top of the docs
• Wires it into .vitepress/theme/index.ts via enhanceApp
• Link scheme is validated to http:/https: so a compromised upstream can't inject a javascript: URL
• Dismissals persist per banner id in localStorage

Used to announce en.dev, and any future cross-site announcements.

Test plan

• Run docs dev server, confirm banner appears at top of page
• Click the \u00d7 \u2014 banner disappears and stays dismissed across reloads
• Clear localStorage jdx-banner-dismissed, reload \u2014 banner returns

\U0001F916 Generated with Claude Code

---

Note

Medium Risk
Moderate risk because it introduces client-side fetching and DOM injection in the docs site (including localStorage persistence and layout offset adjustments), which could affect layout or reliability if the remote endpoint misbehaves.

Overview
Adds a docs-site announcement banner that fetches remote config from https://jdx.dev/banner.json, renders a fixed, dismissible top bar, and persists dismissal per-banner in localStorage (with http/https link validation).

Updates the VitePress theme to initialize the banner via enhanceApp() and adds a new EndevFooter component wired into layout-bottom.

^{Reviewed by Cursor Bugbot for commit d869013. Bugbot is set up for automated code reviews on this repo. Configure here.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.03%. Comparing base (e6ef05c) to head (d869013).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #600   +/-   ##
=======================================
  Coverage   79.03%   79.03%           
=======================================
  Files          48       48           
  Lines        7235     7235           
  Branches     7235     7235           
=======================================
  Hits         5718     5718           
  Misses       1140     1140           
  Partials      377      377           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[greptile-apps]

Greptile Summary

Adds a dismissible cross-site announcement banner to the VitePress docs theme by fetching config from https://jdx.dev/banner.json, along with an EndevFooter component wired into the layout-bottom slot. The implementation uses textContent throughout (XSS-safe) and validates link URLs to http:/https: schemes.

Confidence Score: 5/5

Safe to merge; all remaining findings are P2 style suggestions.

The only new finding is a missing noreferrer on the external link rel attribute — a minor best-practice note. Security model is sound (textContent, scheme validation), and prior P1 concerns about localStorage throwing have already been flagged.

docs/.vitepress/theme/banner.ts — localStorage exception handling (prior thread) and rel attribute

Important Files Changed

Filename	Overview
docs/.vitepress/theme/banner.ts	Fetches and renders a dismissible announcement banner from an external endpoint; uses textContent (XSS-safe) and URL scheme validation. Minor: rel is missing noreferrer, and localStorage.setItem can throw in restricted browsers (see prior thread).
docs/.vitepress/theme/banner.css	Styles for the fixed-position announcement banner; uses VitePress CSS variable for brand colour fallback and includes a responsive breakpoint.
docs/.vitepress/theme/EndevFooter.vue	Simple footer component wired into the layout-bottom slot; hardcodes en.dev branding and MIT license, computes copyright year client-side.
docs/.vitepress/theme/index.ts	Registers EndevFooter in the layout-bottom slot and calls initBanner() via enhanceApp; straightforward wiring with no issues.

Sequence Diagram

sequenceDiagram
    participant Browser
    participant VitePress as VitePress App
    participant Endpoint as jdx.dev/banner.json
    participant LS as localStorage

    VitePress->>Browser: enhanceApp() → initBanner()
    Browser->>Endpoint: fetch(ENDPOINT)
    Endpoint-->>Browser: BannerData { id, enabled, message, link }
    Browser->>LS: getItem("jdx-banner-dismissed")
    alt already dismissed
        LS-->>Browser: b.id (match)
        Browser-->>Browser: skip render
    else not dismissed
        Browser->>Browser: render(b) — inject .jdx-banner into body
        Browser->>Browser: set --vp-layout-top-height via ResizeObserver
        Note over Browser: User clicks ×
        Browser->>LS: setItem("jdx-banner-dismissed", b.id)
        Browser->>Browser: observer.disconnect(), el.remove()
        Browser->>Browser: removeProperty(--vp-layout-top-height)
    end

Loading

_{Reviews (8): Last reviewed commit: "docs: keep --vp-layout-top-height in syn..." | Re-trigger Greptile}

[gemini-code-assist]

Code Review

This pull request introduces a dynamic site banner system for the VitePress documentation, including remote data fetching, local storage-based dismissal, and responsive styling. The review feedback identifies several improvement opportunities: using sticky positioning and theme-standard z-indices for better layout integration, making the initialization logic idempotent, adding robust error handling for local storage access in restricted environments, and preventing potential race conditions during layout height calculations.

[gemini-code-assist]

Using position: relative with a high z-index (60) can cause the banner to overlap the navigation bar incorrectly during scrolling. Additionally, z-index: 60 is higher than the VitePress mobile menu backdrop (50), which can lead to visual glitches where the banner appears on top of the menu overlay.

Changing this to position: sticky ensures it stays at the top and integrates correctly with the --vp-layout-top-height offset used by the VitePress navbar. Using the theme's z-index variable ensures it stays below overlays like the mobile menu.

Suggested change

	position: relative;
	z-index: 60;
	position: sticky;
	top: 0;
	z-index: var(--vp-z-index-nav, 20);

[gemini-code-assist]

The initBanner function should be idempotent to prevent multiple fetches or duplicate banners if enhanceApp is called multiple times (e.g., during HMR).

let isInitialized = false;

export function initBanner(): void {
  if (typeof window === "undefined" || isInitialized) return;
  isInitialized = true;

[gemini-code-assist]

Accessing localStorage can throw exceptions in certain browser configurations (e.g., private mode with blocked cookies). It's safer to wrap this in a try-catch block. Additionally, ensuring the banner has an id before checking dismissal prevents potential logic errors if the API response is incomplete.

      if (!b || !b.enabled || !b.id) return;
      try {
        if (localStorage.getItem(STORAGE_KEY) === b.id) return;
      } catch {
        // Fallback if localStorage is unavailable
      }

[gemini-code-assist]

Similar to the read operation, localStorage.setItem should be wrapped in a try-catch block to avoid crashing the script if storage is restricted.

    try {
      localStorage.setItem(STORAGE_KEY, b.id);
    } catch {}
    el.remove();

[gemini-code-assist]

To prevent potential race conditions where the banner is dismissed before the animation frame fires, check if the element is still in the DOM before updating the layout variable.

  requestAnimationFrame(() => {
    if (el.isConnected) {
      document.documentElement.style.setProperty(
        "--vp-layout-top-height",
        `${el.offsetHeight}px`,
      );
    }
  });