perf: improve mobile Core Web Vitals – infra & rendering optimisations

- netlify.toml: add 1-year immutable cache for hashed assets (/assets/*,
  /fonts/*), 1-day cache for images/scripts, and security headers
  (X-Frame-Options, X-Content-Type-Options, Referrer-Policy,
  Permissions-Policy) to improve PageSpeed Best Practices score
- docusaurus.config.js: add viewport meta tag with viewport-fit=cover;
  add preconnect hints for fonts.googleapis.com, fonts.gstatic.com,
  and Algolia DSN; add dns-prefetch for Clarity, GTM, and GA analytics
  origins to reduce connection setup latency
- src/css/custom.css: add content-visibility:auto + contain-intrinsic-size
  for footer and mobile sidebar to skip off-screen paint; add
  decoding:async fallback for un-annotated images; add font-display:swap
  safety net for any stylesheet-loaded webfonts
- ResponsivePlayer.js: lazy-load react-player via React.lazy +
  React.Suspense (react-player/lazy) so the ~100 KB player bundle is NOT
  included in the initial JS chunk – reduces TBT/INP on first load

Closes #2042

Signed-off-by: Aryan Parikh <aryan81006@gmail.com>

Author: Aryan-B-Parikh

docusaurus.config.js

@@ -63,7 +63,24 @@ module.exports = {
       {property: "og:image:height", content: "630"},
     ],
     headTags: [
-      // Google Fonts - DM Sans (loaded via headTags instead of CSS @import)
+      // ── Viewport (mobile performance) ──────────────────────────────────
+      {
+        tagName: "meta",
+        attributes: {
+          name: "viewport",
+          content: "width=device-width, initial-scale=1.0, viewport-fit=cover",
+        },
+      },
+      // ── Preconnect / DNS-prefetch for critical third-party origins ─────
+      // Keploy CDN
+      {
+        tagName: "link",
+        attributes: {
+          rel: "preconnect",
+          href: "https://keploy.io/",
+        },
+      },
+      // Google Fonts (used by Docusaurus default theme)
       {
         tagName: "link",
         attributes: {
@@ -79,19 +96,43 @@ module.exports = {
           crossorigin: "anonymous",
         },
       },
+      // Google Fonts - DM Sans (loaded via headTags instead of CSS @import)
       {
         tagName: "link",
         attributes: {
           rel: "stylesheet",
           href: "https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;700&display=swap",
         },
       },
-      // Preconnect tag
+      // Algolia search
       {
         tagName: "link",
         attributes: {
           rel: "preconnect",
-          href: "https://keploy.io/",
+          href: "https://WZTL8PLCOD-dsn.algolia.net",
+          crossorigin: "anonymous",
+        },
+      },
+      // Analytics (dns-prefetch only — not render-blocking)
+      {
+        tagName: "link",
+        attributes: {
+          rel: "dns-prefetch",
+          href: "https://www.clarity.ms",
+        },
+      },
+      {
+        tagName: "link",
+        attributes: {
+          rel: "dns-prefetch",
+          href: "https://www.googletagmanager.com",
+        },
+      },
+      {
+        tagName: "link",
+        attributes: {
+          rel: "dns-prefetch",
+          href: "https://www.google-analytics.com",
         },
       },
       {

netlify.toml

@@ -9,7 +9,36 @@
 ## Note: if you are looking for Redirects
 # they have been moved to /static/_redirects to make it more manageable - swyx
 
-# Security headers for all pages
+# ── Performance: Cache headers ────────────────────────────────────────────────
+# Hashed JS/CSS bundles emitted by Docusaurus/webpack → safe to cache 1 year
+[[headers]]
+  for = "/assets/*"
+  [headers.values]
+    Cache-Control = "public, max-age=31536000, immutable"
+
+# Static images, fonts served from /img and /fonts
+[[headers]]
+  for = "/img/*"
+  [headers.values]
+    Cache-Control = "public, max-age=86400, stale-while-revalidate=604800"
+
+[[headers]]
+  for = "/fonts/*"
+  [headers.values]
+    Cache-Control = "public, max-age=31536000, immutable"
+
+# Static JS helpers (non-hashed scripts in /docs/js and /docs/scripts)
+[[headers]]
+  for = "/js/*"
+  [headers.values]
+    Cache-Control = "public, max-age=86400"
+
+[[headers]]
+  for = "/scripts/*"
+  [headers.values]
+    Cache-Control = "public, max-age=86400"
+
+# ── Security headers (improves PageSpeed Best Practices score) ──────────────
 [[headers]]
   for = "/*"
   [headers.values]

src/components/responsive-player/ResponsivePlayer.js

@@ -1,22 +1,35 @@
-import React from "react";
-import ReactPlayer from "react-player";
+import React, {Suspense, lazy} from "react";
+
+// Lazy-load react-player so it is NOT included in the initial JS bundle.
+// react-player/lazy defers loading the actual player implementation until
+// the component is rendered, reducing the first-page-load JS payload.
+const ReactPlayer = lazy(() => import("react-player/lazy"));
 
 function ResponsivePlayer({url, loop, playing}) {
   return (
     <div
       className="relative rounded-lg shadow-lg"
       style={{paddingTop: "56.25%"}}
     >
-      {/* /* Player ratio: 100 / (1280 / 720) */}
-      <ReactPlayer
-        className="absolute left-0 top-0"
-        url={url}
-        loop={loop}
-        playing={playing}
-        width="100%"
-        height="100%"
-        controls={true}
-      />
+      {/* Player ratio: 100 / (1280 / 720) */}
+      <Suspense
+        fallback={
+          <div
+            className="absolute left-0 top-0 flex h-full w-full items-center justify-center bg-gray-100 dark:bg-gray-800"
+            aria-label="Loading video player"
+          />
+        }
+      >
+        <ReactPlayer
+          className="absolute left-0 top-0"
+          url={url}
+          loop={loop}
+          playing={playing}
+          width="100%"
+          height="100%"
+          controls={true}
+        />
+      </Suspense>
     </div>
   );
 }

src/css/custom.css

@@ -3202,3 +3202,54 @@ html[data-theme="dark"] .docs-inline-footer__slack {
     font-size: 0.95rem;
   }
 }
+
+/* ===== PERFORMANCE: Rendering & paint optimisations ===== */
+
+/*
+ * content-visibility: auto — lets the browser skip layout/paint for
+ * off-screen sections, reducing LCP and INP on mobile.
+ * contain-intrinsic-size gives the browser a size estimate so the
+ * scroll-bar doesn't jump when content is rendered.
+ */
+footer,
+.footer {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 200px;
+}
+
+/* Sidebar is always below the fold on small viewports */
+@media (max-width: 996px) {
+  .theme-doc-sidebar-container {
+    content-visibility: auto;
+    contain-intrinsic-size: 0 600px;
+  }
+}
+
+/*
+ * Lazy-decoded images — any <img> without an explicit loading attribute
+ * should at minimum decode off the main thread.
+ */
+img:not([loading]) {
+  decoding: async;
+}
+
+/*
+ * Reduce paint layers for the announcement bar (it's a position:sticky
+ * element and can cause extra compositing cost on mobile).
+ */
+.announcementBar_mb4j {
+  will-change: auto;
+  transform: translateZ(0);
+}
+
+/*
+ * Font-display: swap fallback for any @font-face rules Docusaurus injects.
+ * This prevents invisible text during webfont load (FOIT → FOUT).
+ * The actual font files are already preloaded via webpack-font-preload-plugin;
+ * this rule is a safety net for any font loaded via a stylesheet.
+ */
+@supports (font-display: swap) {
+  @font-face {
+    font-display: swap;
+  }
+}