docs: add cross-site announcement banner by jdx · Pull Request #434 · jdx/fnox

jdx · 2026-04-23T18:14:18Z

Summary

Adds docs/.vitepress/theme/banner.js + banner.css \u2014 a small module that fetches banner config from https://jdx.dev/banner.json and renders a dismissible announcement bar at the top of the docs
Wires it into the existing enhanceApp hook in docs/.vitepress/theme/index.js
Dismissals persist per banner id in localStorage; bumping the id in the source JSON re-shows it to everyone

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

Low Risk
Low risk docs-only UI changes that add a remote-configured banner via fetch/localStorage, with limited impact beyond potential layout/CSP issues if the endpoint is unavailable or blocked.

Overview
Adds a dismissible, cross-site announcement banner to the VitePress docs theme that fetches configuration from https://jdx.dev/banner.json, renders a fixed top bar, and persists dismissals per-banner via localStorage while updating --vp-layout-top-height to avoid layout overlap.

Also adds a simple EndevFooter rendered in the layout-bottom slot to show license/copyright info and an en.dev link with logo, and wires both into docs/.vitepress/theme/index.js.

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

Fetches banner config from https://jdx.dev/banner.json and renders a dismissible top-of-page announcement. Dismissals persist per banner id in localStorage, so bumping the id re-shows it. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

gemini-code-assist

Code Review

This pull request introduces a dynamic announcement banner for the VitePress documentation, including a new CSS file for styling, a JavaScript module for fetching and rendering the banner, and integration into the theme's enhancement hook. The review feedback suggests several improvements: using fixed positioning to prevent layout gaps with the navbar, enhancing API response validation and type safety, wrapping storage access in a try-catch block for better compatibility, and adding a resize listener to ensure the layout height remains synchronized.

gemini-code-assist · 2026-04-23T18:17:45Z

@@ -0,0 +1,37 @@
+.jdx-banner {
+  position: relative;


Using position: relative for the banner while setting the --vp-layout-top-height variable will cause layout issues in VitePress. Since the VitePress navbar is typically fixed or sticky and uses this variable for its top offset, a relative banner will scroll out of view while the navbar remains offset from the top of the viewport, leaving a blank gap. To ensure the banner and navbar stay synchronized, the banner should use position: fixed.

Suggested change

position: relative;

position: fixed;

top: 0;

left: 0;

right: 0;

gemini-code-assist · 2026-04-23T18:17:45Z

+      if (!b || !b.enabled) return;
+      if (localStorage.getItem(STORAGE_KEY) === b.id) return;


Added validation for b.id and b.message to prevent rendering an empty or broken banner if the API response is incomplete. Also, ensured the ID comparison is type-safe by casting b.id to a string, as localStorage always returns strings and the JSON might provide a numeric ID.

Suggested change

if (!b || !b.enabled) return;

if (localStorage.getItem(STORAGE_KEY) === b.id) return;

if (!b || !b.enabled || !b.id || !b.message) return

if (localStorage.getItem(STORAGE_KEY) === String(b.id)) return

gemini-code-assist · 2026-04-23T18:17:45Z

+  btn.setAttribute("aria-label", "Dismiss");
+  btn.textContent = "\u00d7";
+  btn.addEventListener("click", () => {
+    localStorage.setItem(STORAGE_KEY, b.id);


Accessing localStorage.setItem can throw a SecurityError in some browser environments (e.g., when third-party cookies/storage are blocked). Wrapping this in a try-catch ensures that the banner can still be dismissed from the UI even if the dismissal cannot be persisted.

Suggested change

localStorage.setItem(STORAGE_KEY, b.id);

try { localStorage.setItem(STORAGE_KEY, b.id) } catch (e) {}

gemini-code-assist · 2026-04-23T18:17:45Z

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


The banner height is only calculated once. If the window is resized (e.g., rotating a mobile device or resizing the browser), the banner's height might change due to text wrapping or the media query at 640px. This would leave the --vp-layout-top-height variable out of sync with the actual banner height. Consider adding a resize event listener to update this value dynamically.

greptile-apps · 2026-04-23T18:18:21Z

Greptile Summary

This PR adds a cross-site announcement banner (fetched from jdx.dev/banner.json) and an EndevFooter component. The isHttpUrl guard correctly blocks javascript: and data: URL injection, and SSR is safely handled by the typeof window guard at the top of initBanner.

Several issues noted in previous review threads — missing noreferrer, no duplicate-element guard, and b.id type-coercion bugs on the localStorage comparison — remain unaddressed and are worth resolving before shipping.

Confidence Score: 4/5

Safe to review further after addressing outstanding prior-thread issues; new code is otherwise well-structured.

The XSS concern from prior threads is now fixed via isHttpUrl. However, three P1 issues flagged in earlier review rounds remain in the code: missing noreferrer on the _blank link, no idempotency guard against duplicate banner elements (e.g. HMR), and the localStorage strict-equality comparison against a potentially numeric b.id. These are not re-raised as new inline comments per review policy, but they do affect merge readiness.

docs/.vitepress/theme/banner.js — outstanding type-coercion and idempotency issues from prior threads

Important Files Changed

Filename	Overview
docs/.vitepress/theme/banner.js	Core banner module: fetches remote config, guards XSS via `isHttpUrl`, handles SSR. Several issues flagged in prior threads (numeric b.id comparison, missing duplicate guard, missing noreferrer) remain unaddressed in this revision.
docs/.vitepress/theme/banner.css	Clean, responsive CSS for the banner; uses VitePress brand token with fallback, positions dismiss button absolutely, and includes a mobile breakpoint.
docs/.vitepress/theme/EndevFooter.vue	Simple footer component using `layout-bottom` slot; year is computed at setup time (SSG builds will bake in the build year) and logo is fetched from an external GitHub URL.
docs/.vitepress/theme/index.js	Wires `initBanner` into `enhanceApp` and `EndevFooter` into the `layout-bottom` slot; minimal and correct integration.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A([enhanceApp called]) --> B{typeof window\n=== 'undefined'?}
    B -- yes --> C([SSR: return early])
    B -- no --> D[fetch jdx.dev/banner.json]
    D --> E{r.ok?}
    E -- no --> F([silent catch: no banner])
    E -- yes --> G[parse JSON]
    G --> H{b && b.enabled?}
    H -- no --> F
    H -- yes --> I{localStorage\n=== b.id?}
    I -- yes --> J([already dismissed: no banner])
    I -- no --> K[render banner div]
    K --> L[isHttpUrl guard\nfor b.link]
    L --> M[prepend to body]
    M --> N[requestAnimationFrame\nset --vp-layout-top-height]
    M --> O[ResizeObserver\nsyncHeight on resize]
    N --> P([Banner visible])
    O --> P
    P --> Q{User clicks ×}
    Q --> R[localStorage.setItem b.id]
    R --> S[el.remove]
    S --> T[removeProperty --vp-layout-top-height]
    T --> U([Banner dismissed])

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

Only allow http(s): links from the upstream JSON. Defense-in-depth against a compromised jdx.dev injecting a javascript: URL that would execute arbitrary code in the docs origin on click. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

greptile-apps · 2026-04-23T18:23:22Z

+    .then((r) => (r.ok ? r.json() : null))
+    .then((b) => {
+      if (!b || !b.enabled) return;
+      if (localStorage.getItem(STORAGE_KEY) === b.id) return;


Dismiss silently fails when b.id is missing

If banner.json omits the id field, b.id is undefined. localStorage.getItem(STORAGE_KEY) === undefined always evaluates to false (storage returns null or a string, never undefined), so the early-return never fires and the banner re-appears on every reload. On dismiss, localStorage.setItem(STORAGE_KEY, undefined) stores the literal string "undefined", which still never equals undefined, making the banner permanently undismissable.

Add a guard to skip rendering when id is absent:

Suggested change

if (localStorage.getItem(STORAGE_KEY) === b.id) return;

if (!b || !b.enabled || !b.id) return;

if (localStorage.getItem(STORAGE_KEY) === b.id) return;

cursor · 2026-04-23T18:24:05Z

+    .then((r) => (r.ok ? r.json() : null))
+    .then((b) => {
+      if (!b || !b.enabled) return;
+      if (localStorage.getItem(STORAGE_KEY) === b.id) return;


Strict equality breaks dismissal for numeric banner IDs

Medium Severity

localStorage.getItem() always returns a string, but b.id from the parsed JSON may be a number. The strict equality check (===) on line 12 means "1" === 1 evaluates to false, so a dismissed banner reappears on every page load. localStorage.setItem coerces the value to a string on dismiss, but the next fetch produces a numeric b.id again, and the comparison fails.

Additional Locations (1)

docs/.vitepress/theme/banner.js#L50-L51

^{Reviewed by Cursor Bugbot for commit fed9300. Configure here.}

Banner was using position: relative which put it in document flow *and* VitePress applies --vp-layout-top-height offset, causing content to be pushed down twice. Switch to position: fixed so the banner is out of flow and --vp-layout-top-height alone handles the content offset (which is what VitePress's layout-top slot assumes). Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

greptile-apps · 2026-04-23T18:31:41Z

+    .then((r) => (r.ok ? r.json() : null))
+    .then((b) => {
+      if (!b || !b.enabled) return;
+      if (localStorage.getItem(STORAGE_KEY) === b.id) return;


Numeric b.id breaks dismiss persistence

localStorage.getItem() always returns a string (or null), but b.id from JSON.parse can be a number (e.g. {"id": 1}). The strict-equality check === b.id then fails on the next load because "1" === 1 is false — and the same mismatch occurs on line 51 when setItem coerces the number to "1" but the live value is still 1. The banner becomes permanently undismissable for any visitor as long as id stays numeric in banner.json.

Coerce to a string on both sides:

Suggested change

if (localStorage.getItem(STORAGE_KEY) === b.id) return;

if (localStorage.getItem(STORAGE_KEY) === String(b.id)) return;

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit bea2d0b. Configure here.}

- Bump z-index to 1001 so the banner sits above custom nav overrides (e.g. hk's .VPNav at z-index: 1000 !important). - Use dark text on light brand backgrounds (coral/pink/gold/cyan) for readable contrast. Sites with dark brand backgrounds keep white text. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Adds a small footer with license, copyright, and link back to en.dev, matching the footer used on the mise docs. Rendered via VitePress's layout-bottom slot. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

- Center message+link in the banner, position dismiss button absolutely at the right edge so it doesn't skew the centering. - Drop rel=noreferrer on the link so en.dev gets analytics attribution for traffic from the docs. Keep rel=noopener for security. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Left/right padding was asymmetric (1rem vs 2.75rem desktop; 0.75rem vs 2.5rem mobile), which shifted the "centered" text off from true viewport center. Match the sides so justify-content: center lines up with the viewport midpoint. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

no-cache forces a conditional GET on every page load. The server sends Cache-Control: public, max-age=300, must-revalidate, so default browser caching already gives 5-min freshness, which is plenty for an announcement banner. Returning users with a dismissed banner also already short-circuit via localStorage before the fetch runs anyway. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

The previous fallback (#3451b2, VitePress default dark blue) made black banner text unreadable if --vp-c-brand-1 ever fails to resolve. Use a fallback that matches this site's actual brand color so black text stays readable in the fallback scenario. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

The height CSS variable was set once in a single rAF and never updated afterward. On window resize, orientation change, or text reflow the banner height could change, leaving the VitePress nav offset stale and causing overlap or a visible gap. Observe the banner element and resync the variable whenever its size changes; disconnect the observer when the banner is dismissed. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

@bglusman

@bglusman

@bglusman

## Upstream release Bumps bundled fnox binary from 1.20.0 to 1.22.0. **Release**: https://github.com/jdx/fnox/releases/tag/v1.22.0 ## Release notes v1.22.0 introduces a top-level library API for embedding fnox in Rust applications, and fixes a sharp edge in `fnox set` that could turn an encrypted secret into plaintext. ## Added **Top-level `Fnox` library API** ([#442](jdx/fnox#442)) -- @bglusman Downstream Rust consumers can now use fnox as a library in three lines instead of replicating the internals of `GetCommand::run`: ```rust use fnox::Fnox; let fnox = Fnox::discover()?; // walks up + merges parent + local + global config let value = fnox.get("MY_KEY").await?; let names = fnox.list()?; ``` The new `Fnox` type lives in `src/library.rs` and is re-exported from the crate root. Highlights: - `Fnox::discover()` mirrors the binary's full config-discovery and merge chain via `Config::load_smart`, including the `FNOX_PROFILE` env var. - `Fnox::open(path)` loads an explicit config without the upward-search/merge behavior. - `Fnox::with_profile("staging")` builder for non-default profiles. - `get()` returns `FnoxError::SecretNotFound` with a populated "Did you mean…" suggestion, matching the CLI's UX so callers don't need to recompute it. - `Fnox` is cheap to clone (`Config` is held behind an `Arc`) and safe to hold across `.await`. `set()` is intentionally not part of this first cut; it'll get its own design pass. ## Fixed **`fnox set` no longer silently downgrades encrypted secrets to plaintext** ([#439](jdx/fnox#439)) -- @rpendleton When multiple providers were configured without a `default_provider`, running `fnox set` on an existing secret without `--provider` would write the new value as plaintext while leaving the original `provider = "..."` key in place. The next `fnox get` then failed trying to "decrypt" a value that was no longer encrypted. `fnox set` now reuses the secret's existing provider before falling back to `default_provider` or plaintext, so updates stay encrypted and readable without having to pass `--provider` on every call: ```bash fnox set --provider age MY_SECRET "original-value" # encrypted with age fnox set MY_SECRET "new-value" # still encrypted with age ``` **Deterministic provider ordering in the generated schema** ([#432](jdx/fnox#432)) -- @jdx Within-category provider ordering in `build/generate_providers.rs` was inheriting `fs::read_dir` order, which is OS- and filesystem-dependent. That non-determinism flowed into `docs/public/schema.json` and caused autofix.ci to keep reshuffling 100+ lines between runs. A secondary sort by provider name fixes the churn; running `fnox schema` twice now produces byte-identical output. **Mobile docs banner layout** ([#437](jdx/fnox#437)) -- @jdx At `<=640px` the announcement banner now switches to a column layout with the close button pinned to the top-right corner, instead of cramming the message and "Read more" link onto one squeezed line. ## Changed - Docs site nav now shows the current release version (read from `Cargo.toml` at build time) and a GitHub star count, matching the mise/aube docs ([#443](jdx/fnox#443)) -- @jdx - Added a dismissible cross-site announcement banner that fetches its config from `jdx.dev/banner.json` and respects the `expires` field ([#434](jdx/fnox#434), [#436](jdx/fnox#436)) -- @jdx ## New Contributors * @bglusman made their first contribution in [#442](jdx/fnox#442) **Full Changelog**: jdx/fnox@v1.21.0...v1.22.0 ## 💚 Sponsor fnox fnox is maintained by [@jdx](https://github.com/jdx) under [**en.dev**](https://en.dev) — a small independent studio building developer tooling like [mise](https://mise.jdx.dev/), [aube](https://aube.en.dev/), hk, and more. Keeping fnox secure, maintained, and free is funded by sponsors. If fnox is handling secrets or config for you or your team, please consider [sponsoring at en.dev](https://en.dev). Sponsorships are what let fnox stay independent and the project keep moving. Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

## Summary - Adds `docs/.vitepress/theme/banner.js` + `banner.css` \u2014 a small module that fetches banner config from `https://jdx.dev/banner.json` and renders a dismissible announcement bar at the top of the docs - Wires it into the existing `enhanceApp` hook in `docs/.vitepress/theme/index.js` - Dismissals persist per banner id in `localStorage`; bumping the id in the source JSON re-shows it to everyone 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](https://claude.com/claude-code)  --- > [!NOTE] > **Low Risk** > Low risk docs-only UI changes that add a remote-configured banner via `fetch`/`localStorage`, with limited impact beyond potential layout/CSP issues if the endpoint is unavailable or blocked. > > **Overview** > Adds a dismissible, cross-site announcement banner to the VitePress docs theme that fetches configuration from `https://jdx.dev/banner.json`, renders a fixed top bar, and persists dismissals per-banner via `localStorage` while updating `--vp-layout-top-height` to avoid layout overlap. > > Also adds a simple `EndevFooter` rendered in the `layout-bottom` slot to show license/copyright info and an `en.dev` link with logo, and wires both into `docs/.vitepress/theme/index.js`. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 5c6d2cf. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>  --------- Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]> Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

@bglusman

@bglusman

jdx and others added 2 commits April 23, 2026 13:14

[autofix.ci] apply automated fixes

842162a

gemini-code-assist Bot reviewed Apr 23, 2026

View reviewed changes

greptile-apps Bot reviewed Apr 23, 2026

View reviewed changes

Comment thread docs/.vitepress/theme/banner.js

Comment thread docs/.vitepress/theme/banner.js

Comment thread docs/.vitepress/theme/banner.js

greptile-apps Bot reviewed Apr 23, 2026

View reviewed changes

cursor Bot reviewed Apr 23, 2026

View reviewed changes

greptile-apps Bot reviewed Apr 23, 2026

View reviewed changes

cursor Bot reviewed Apr 23, 2026

View reviewed changes

Comment thread docs/.vitepress/theme/banner.css Outdated

jdx and others added 7 commits April 23, 2026 13:46

docs: add en.dev footer

e5df64f

Adds a small footer with license, copyright, and link back to en.dev, matching the footer used on the mise docs. Rendered via VitePress's layout-bottom slot. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

jdx enabled auto-merge (squash) April 23, 2026 19:51

jdx merged commit 3d18339 into main Apr 23, 2026
16 checks passed

jdx deleted the feat/site-banner branch April 23, 2026 19:54

mise-en-dev mentioned this pull request Apr 23, 2026

chore: release v1.22.0 #433

Merged

mise-en-dev mentioned this pull request Apr 26, 2026

chore: release v1.23.0 #445

Merged

BrewTestBot mentioned this pull request Apr 26, 2026

fnox 1.22.0 Homebrew/homebrew-core#279529

Merged

github-actions Bot mentioned this pull request Apr 26, 2026

chore: bump bundled fnox to 1.22.0 fullerzz/fnox-py#10

Merged

-  position: relative;
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;

		if (!b \|\| !b.enabled) return;
		if (localStorage.getItem(STORAGE_KEY) === b.id) return;

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

	if (localStorage.getItem(STORAGE_KEY) === b.id) return;
	if (!b \|\| !b.enabled \|\| !b.id) return;
	if (localStorage.getItem(STORAGE_KEY) === b.id) return;

Uh oh!

Conversation

jdx commented Apr 23, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Flowchart

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Apr 23, 2026

Choose a reason for hiding this comment

Strict equality breaks dismissal for numeric banner IDs

Uh oh!

greptile-apps Bot Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jdx commented Apr 23, 2026 •

edited by cursor Bot

Loading

greptile-apps Bot commented Apr 23, 2026 •

edited

Loading