Merge branch 'cursor/merge-branch-into-main-3992'

cursoragent · cursoragent · commit 1fa8157638df · 2025-11-08T21:42:36.000Z
diff --git a/docs-site/docusaurus.config.js b/docs-site/docusaurus.config.js
@@ -53,6 +53,19 @@ const config = {
     ],
   ],
 
+  plugins: [
+    [
+      require.resolve('@easyops-cn/docusaurus-search-local'),
+      {
+        hashed: true,
+        highlightSearchTermsOnTargetPage: true,
+        docsRouteBasePath: '/docs',
+        indexBlog: false,
+        language: ['en'],
+      },
+    ],
+  ],
+
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
@@ -82,6 +95,10 @@ const config = {
             label: 'npm',
             position: 'right',
           },
+          {
+            type: 'search',
+            position: 'right',
+          },
         ],
       },
       footer: {
diff --git a/docs-site/package.json b/docs-site/package.json
@@ -17,6 +17,7 @@
     "@docusaurus/core": "^3.9.2",
     "@docusaurus/preset-classic": "^3.9.2",
     "@mdx-js/react": "^3.1.1",
+    "@easyops-cn/docusaurus-search-local": "^0.44.0",
     "clsx": "^2.1.1",
     "prism-react-renderer": "^2.4.1",
     "react": "^18.3.1",
diff --git a/docs-site/src/pages/index.js b/docs-site/src/pages/index.js
@@ -3,70 +3,123 @@ import Layout from '@theme/Layout';
 import Link from '@docusaurus/Link';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import useBaseUrl from '@docusaurus/useBaseUrl';
+import {useColorMode} from '@docusaurus/theme-common';
 import clsx from 'clsx';
 import styles from './index.module.css';
 
-const features = [
+const pillars = [
   {
     icon: '🛡️',
-    title: 'Resilient Middleware',
+    title: 'Crash guard for every handler',
     description:
-      'Prevent crashes across every Express route with a zero-dependency runtime guard that isolates failures and keeps traffic flowing.',
+      'Automatically wraps Express routes so unhandled sync or async errors resolve to consistent JSON responses instead of crashing the process.',
   },
   {
-    icon: '📊',
-    title: 'Built-in Observability',
+    icon: '📈',
+    title: 'Dashboards without agents',
     description:
-      'Ship production dashboards, traces, and metrics out of the box—no vendor lock-in, agents, or sidecars required.',
+      'Ship the built-in Crashless UI at `/_crashless` for live throughput, percentile latency, and error analytics—no vendor lock-in or sidecars.',
   },
   {
-    icon: '⚙️',
-    title: 'Optimized for Node.js',
+    icon: '🧭',
+    title: 'Trace-first instrumentation',
     description:
-      'Crafted specifically for Node.js APIs with <5ms overhead per request and native support for async/await workflows.',
+      'AsyncLocalStorage-powered tracing, fetch/fs auto-patching, and OTLP exports come ready to toggle on when you want deep visibility.',
+  },
+  {
+    icon: '🔐',
+    title: 'Production-safe by default',
+    description:
+      'Mask sensitive payloads, gate dashboards with token or IP checks, and stream metrics securely with zero runtime npm dependencies.',
   },
 ];
 
 const highlights = [
-  {value: '<5ms', label: 'Median request overhead'},
-  {value: '99.99%', label: 'Crash-free uptime with guards enabled'},
-  {value: '60s', label: 'Time to first dashboard'},
-  {value: '0', label: 'Third-party dependencies required'},
+  {value: '1', label: 'line to enable crash prevention'},
+  {value: '+2.3%', label: 'overhead in minimal guard mode'},
+  {value: '60s', label: 'to first dashboard at /_crashless'},
+  {value: '0', label: 'runtime npm dependencies'},
 ];
 
-const rollouts = [
+const playbook = [
+  {
+    title: 'Drop the middleware in',
+    description:
+      'Add crashless() to your Express app and keep every existing handler—async patching and error normalization happen automatically.',
+  },
   {
-    title: 'Drop-in install',
+    title: 'Open the live console',
     description:
-      'Add the Crashless middleware to any existing Express app with a single import and immediate protection.',
+      'Visit the built-in dashboard for request metrics, latency percentiles, and crash analytics powered by the in-memory registry.',
   },
   {
-    title: 'Instrument automatically',
+    title: 'Tune telemetry intentionally',
     description:
-      'Capture traces, metrics, and alerts without touching your handlers—Crashless hooks into core Node.js primitives.',
+      'Follow the docs to flip between minimal guards, built-in metrics, or trace sampling depending on the environment you’re deploying.',
   },
   {
-    title: 'Operate with confidence',
+    title: 'Export when you need to share',
     description:
-      'Unified dashboards highlight hotspots, slow transactions, and error bursts so you can resolve issues before users notice.',
+      'Expose Prometheus and OTLP endpoints out-of-the-box so Grafana, Datadog, or OpenTelemetry collectors can ingest your data.',
+  },
+];
+
+const docsSpotlight = [
+  {
+    title: 'Getting Started',
+    description: 'Install in one minute, protect routes instantly, and access the dashboard locally.',
+    to: '/docs/getting-started',
+    badge: 'Start here',
+  },
+  {
+    title: 'Configuration',
+    description: 'Dial in telemetry engines, security, sampling, and dashboard access for every stage.',
+    to: '/docs/configuration',
+    badge: 'Tweak settings',
+  },
+  {
+    title: 'Architecture',
+    description: 'Learn how zero-dependency middleware, AsyncLocalStorage, and the metrics registry work together.',
+    to: '/docs/architecture',
+    badge: 'Under the hood',
+  },
+  {
+    title: 'Examples',
+    description: 'Copy production-ready patterns for exporters, dashboards, tracing, and rollout strategies.',
+    to: '/docs/examples',
+    badge: 'Copy & paste',
   },
 ];
 
-const codeExample = `import crashless from 'crashless';
+const codeExample = `import express from 'express';
+import crashless from 'crashless';
+
+const app = express();
 
 app.use(
   crashless({
-    dashboards: true,
-    tracing: { sampler: { probability: 0.1 } },
+    appName: 'Checkout API',
+    telemetry: {
+      engine: 'builtin',
+      dashboard: true,
+      traces: { enabled: true, samplingRate: 0.2 },
+    },
+    enableDashboard: true,
+    dashboardAuth: req => req.ip === '127.0.0.1',
   }),
 );
 
-app.get('/checkout', crashless.route(async (req, res) => {
-  const result = await runBusinessLogic(req.body);
-  res.json(result);
-}));
+app.get('/checkout', async (req, res) => {
+  const order = await placeOrder(req.body);
 
-await crashless.start();`;
+  if (!order.ok) {
+    throw crashless.createError('Payment declined', 402, 'ERR_PAYMENT');
+  }
+
+  res.json(order.data);
+});
+
+app.listen(3000);`;
 
 function FeatureCard({icon, title, description}) {
   return (
@@ -96,64 +149,77 @@ function RolloutStep({title, description}) {
   );
 }
 
+function DocCard({title, description, to, badge}) {
+  return (
+    <Link to={to} className={styles.docsCard}>
+      <span className={styles.docsBadge}>{badge}</span>
+      <h3>{title}</h3>
+      <p>{description}</p>
+      <span className={styles.docsArrow}>Read the guide →</span>
+    </Link>
+  );
+}
+
 export default function Home() {
   const {siteConfig} = useDocusaurusContext();
   const heroImageUrl = useBaseUrl('img/banner.png');
+  const {colorMode} = useColorMode();
+  const stackblitzTheme = colorMode === 'dark' ? 'dark' : 'light';
+  const stackblitzUrl =
+    'https://stackblitz.com/github/sunnyghodeswar/crashless-examples?file=examples%2Fexample-one-liner.js&embed=1&hideExplorer=1&hideNavigation=1&view=preview';
+  const stackblitzSrc = `${stackblitzUrl}&theme=${stackblitzTheme}`;
 
   return (
     <Layout
       title={siteConfig.title}
-      description="Crashless delivers production-grade observability and crash prevention for Node.js APIs with zero extra dependencies.">
+      description="Crashless delivers crash prevention, distributed tracing, and live dashboards for Node.js APIs without adding dependencies.">
       <main className={styles.main}>
         <section className={styles.hero}>
           <div className={styles.heroContent}>
-            <span className={styles.heroBadge}>Observability built for Node.js</span>
-            <h1 className={styles.heroTitle}>Crashless</h1>
-            <p className={styles.heroSubtitle}>
-              Production-ready crash prevention and monitoring without agents, vendors, or friction.
-            </p>
+            <span className={styles.heroBadge}>Zero-dependency observability</span>
+            <h1 className={styles.heroTitle}>Crashless keeps your Node.js APIs online</h1>
+            <p className={styles.heroSubtitle}>Stop production crashes from stray async errors and unlock dashboards in seconds.</p>
             <p className={styles.heroDescription}>
-              Harden your Express apps with protective middleware, real-time dashboards, actionable alerts, and full-stack traces—all activated in minutes.
+              Wrap Express once to enforce consistent error handling, stream rich telemetry, and export traces—all while staying in
+              control of overhead.
             </p>
             <div className={styles.heroActions}>
               <Link className={clsx('button button--primary button--lg', styles.primaryButton)} to="/docs/getting-started">
-                Start in 60 seconds
+                Install in one minute
               </Link>
               <Link className="button button--outline button--lg" to="/docs/architecture">
                 Explore the architecture
               </Link>
             </div>
-            <div className={styles.heroFootnote}>Zero agents. Zero downtime during rollout.</div>
+            <div className={styles.heroFootnote}>MIT licensed • Works with Express 4 & 5 • Node.js 18+</div>
           </div>
           <div className={styles.heroMedia}>
             <img src={heroImageUrl} alt="Crashless dashboard preview" className={styles.heroImage} loading="lazy" />
             <div className={styles.heroCallout}>
-              <span className={styles.heroCalloutLabel}>Live insights</span>
-              <p>Automatic anomaly detection, latency breakdowns, and error analytics without extra wiring.</p>
+              <span className={styles.heroCalloutLabel}>Telemetry included</span>
+              <p>Percentile latency, crash analytics, Prometheus exports, and AsyncLocalStorage traces with zero extra services.</p>
             </div>
           </div>
         </section>
 
         <section className={styles.trustStrip}>
-          <p className={styles.trustLabel}>Trusted by teams delivering high-availability Node.js services</p>
+          <p className={styles.trustLabel}>Everything teams need in one guardrail-first package</p>
           <div className={styles.trustTags}>
-            <span>Fintech</span>
-            <span>SaaS</span>
-            <span>E-commerce</span>
-            <span>Media</span>
+            <span>Async error shields</span>
+            <span>Built-in dashboards</span>
+            <span>Prometheus & OTLP</span>
+            <span>Token/IP gating</span>
           </div>
         </section>
 
         <section className={styles.featureSection}>
           <div className={styles.sectionHeader}>
             <span className={styles.sectionBadge}>Why Crashless</span>
-            <h2>Everything you need to keep APIs resilient</h2>
-            <p>
-              Crashless combines defensive middleware with observability guardrails so teams can focus on product, not plumbing.
-            </p>
+            <h2>All-in-one resilience for Node.js APIs</h2>
+            <p>Crashless merges crash prevention, observability, and secure operations into a single install so you can focus on shipping product.</p>
           </div>
           <div className={styles.featureGrid}>
-            {features.map(feature => (
+            {pillars.map(feature => (
               <FeatureCard key={feature.title} {...feature} />
             ))}
           </div>
@@ -168,30 +234,66 @@ export default function Home() {
         <section className={styles.rolloutSection}>
           <div className={styles.sectionHeader}>
             <span className={styles.sectionBadge}>Rollout playbook</span>
-            <h2>Upgrade observability without rewriting your stack</h2>
-            <p>Follow a clear path from installation to insight, backed by automation at every step.</p>
+            <h2>Go from install to insight without rewrites</h2>
+            <p>Follow the adoption path outlined in the docs: start with guards, then layer in dashboards, metrics, and traces as you need them.</p>
           </div>
           <div className={styles.rolloutGrid}>
-            {rollouts.map(step => (
+            {playbook.map(step => (
               <RolloutStep key={step.title} {...step} />
             ))}
           </div>
         </section>
 
+        <section className={styles.docsSection}>
+          <div className={styles.sectionHeader}>
+            <span className={styles.sectionBadge}>Docs that go deep</span>
+            <h2>Everything documented, from hello world to internals</h2>
+            <p>Dive into the guides to configure telemetry, understand the architecture, and copy production-ready patterns straight into your app.</p>
+          </div>
+          <div className={styles.docsGrid}>
+            {docsSpotlight.map(doc => (
+              <DocCard key={doc.title} {...doc} />
+            ))}
+          </div>
+        </section>
+
+        <section className={styles.playgroundSection}>
+          <div className={styles.sectionHeader}>
+            <span className={styles.sectionBadge}>Try it live</span>
+            <h2>Experiment with Crashless in your browser</h2>
+            <p>Spin up the StackBlitz demo to explore middleware guards, dashboards, and tracing without leaving the docs.</p>
+          </div>
+          <div className={styles.playgroundFrameWrapper}>
+            <iframe
+              src={stackblitzSrc}
+              title="Crashless StackBlitz Demo"
+              loading="lazy"
+              allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
+              allowFullScreen
+            />
+          </div>
+          <div className={styles.playgroundFooter}>
+            <span>Prefer a full tab?</span>
+            <Link to={stackblitzUrl} className="button button--link">
+              Open StackBlitz demo →
+            </Link>
+          </div>
+        </section>
+
         <section className={styles.codeSection}>
           <div className={styles.sectionHeader}>
             <span className={styles.sectionBadge}>See how it works</span>
-            <h2>Instrument your Express app in minutes</h2>
-            <p>Crashless wraps your existing routes to guarantee reliability while streaming telemetry to your dashboard.</p>
+            <h2>Protect handlers and surface telemetry with one import</h2>
+            <p>Crashless instruments Express while letting you choose how much observability to enable for each environment.</p>
           </div>
           <div className={styles.codeBlock}>
             <pre>
               <code>{codeExample}</code>
             </pre>
           </div>
           <div className={styles.codeActions}>
-            <Link className="button button--link" to="/docs/api-reference">
-              View the full API reference →
+            <Link className="button button--link" to="/docs/configuration">
+              Review configuration options →
             </Link>
             <Link className="button button--link" to="/docs/examples">
               Browse production-ready examples →
@@ -201,13 +303,11 @@ export default function Home() {
 
         <section className={styles.ctaSection}>
           <div className={styles.ctaCard}>
-            <h2>Ship reliable Node.js services faster</h2>
-            <p>
-              Join teams that ship resilient APIs with instant crash protection, best-in-class observability, and zero operational overhead.
-            </p>
+            <h2>Ship resilient Node.js services without the overhead</h2>
+            <p>Deploy Crashless to stay crash-free, watch live metrics, and export telemetry to your existing observability stack whenever you need it.</p>
             <div className={styles.heroActions}>
               <Link className={clsx('button button--primary button--lg', styles.primaryButton)} to="/docs/getting-started">
-                Get started
+                Start in 60 seconds
               </Link>
               <Link className="button button--secondary button--lg" to="/docs/performance">
                 See performance benchmarks
diff --git a/docs-site/src/pages/index.module.css b/docs-site/src/pages/index.module.css
