From 99cdbc83a9296d2e17aa6f4b74342db6f8806667 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 1 Jul 2025 23:44:02 +0000
Subject: [PATCH 1/3] Initial plan


From 10f3e5dbb3e6b4c82989f1ab6a663c794b49b943 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 1 Jul 2025 23:58:41 +0000
Subject: [PATCH 2/3] Add comprehensive tooltips to cache analysis fields

Co-authored-by: serhalp <1377702+serhalp@users.noreply.github.com>
---
 app/components/CacheAnalysis.vue |  27 ++++-
 app/utils/tooltips.ts            | 172 +++++++++++++++++++++++++++++++
 2 files changed, 196 insertions(+), 3 deletions(-)
 create mode 100644 app/utils/tooltips.ts

diff --git a/app/components/CacheAnalysis.vue b/app/components/CacheAnalysis.vue
index a13b0a1..0d0fbee 100644
--- a/app/components/CacheAnalysis.vue
+++ b/app/components/CacheAnalysis.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { formatDuration, intervalToDuration } from 'date-fns'
+import { getFieldTooltip, getCacheNameTooltip, getForwardReasonTooltip, formatTooltip } from '~/utils/tooltips'
 
 const props = defineProps<{
   cacheHeaders: Record<string, string>
@@ -61,10 +62,10 @@ onUnmounted(() => {
 <template>
   <div class="container">
     <div>
-      Served by: <strong>{{ cacheAnalysis.servedBy.source }}</strong>
+      <span :title="formatTooltip(getFieldTooltip('served-by'))">Served by:</span> <strong>{{ cacheAnalysis.servedBy.source }}</strong>
     </div>
     <div>
-      CDN node(s): <code>{{ cacheAnalysis.servedBy.cdnNodes }}</code>
+      <span :title="formatTooltip(getFieldTooltip('cdn-nodes'))">CDN node(s):</span> <code>{{ cacheAnalysis.servedBy.cdnNodes }}</code>
     </div>
 
     <hr />
@@ -88,7 +89,7 @@ onUnmounted(() => {
         <!-- This is a bit of a hack to use the pretty <dt> styling but with sections. -->
         <!-- I should probably just do something custom instead. -->
         <dt class="cache-heading">
-          <h4>
+          <h4 :title="formatTooltip(getCacheNameTooltip(cacheName))">
             ↳ <em>{{ cacheName }}</em> cache
           </h4>
         </dt>
@@ -97,6 +98,7 @@ onUnmounted(() => {
         <dt
           class="data-key"
           :class="{ 'key-highlighted': isKeyHovered(`Hit-${cacheIndex}`) }"
+          :title="formatTooltip(getFieldTooltip('hit'))"
           @mouseenter="handleDataKeyHover(`Hit-${cacheIndex}`, parameters.hit)"
           @mouseleave="handleDataKeyLeave"
         >
@@ -117,6 +119,7 @@ onUnmounted(() => {
           <dt
             class="data-key"
             :class="{ 'key-highlighted': isKeyHovered(`Forwarded because-${cacheIndex}`) }"
+            :title="formatTooltip(getFieldTooltip('forwarded-because'))"
             @mouseenter="handleDataKeyHover(`Forwarded because-${cacheIndex}`, parameters.fwd)"
             @mouseleave="handleDataKeyLeave"
           >
@@ -129,6 +132,7 @@ onUnmounted(() => {
               'value-matching': isKeyHovered(`Forwarded because-${cacheIndex}`) && isValueMatching(parameters.fwd),
               'value-different': isKeyHovered(`Forwarded because-${cacheIndex}`) && !isValueMatching(parameters.fwd),
             }"
+            :title="formatTooltip(getForwardReasonTooltip(parameters.fwd))"
           >
             {{ parameters.fwd }}
           </dd>
@@ -138,6 +142,7 @@ onUnmounted(() => {
           <dt
             class="data-key"
             :class="{ 'key-highlighted': isKeyHovered(`Forwarded status-${cacheIndex}`) }"
+            :title="formatTooltip(getFieldTooltip('forwarded-status'))"
             @mouseenter="handleDataKeyHover(`Forwarded status-${cacheIndex}`, parameters['fwd-status'])"
             @mouseleave="handleDataKeyLeave"
           >
@@ -159,6 +164,7 @@ onUnmounted(() => {
           <dt
             class="data-key"
             :class="{ 'key-highlighted': isKeyHovered(`TTL-${cacheIndex}`) }"
+            :title="formatTooltip(getFieldTooltip('ttl'))"
             @mouseenter="handleDataKeyHover(`TTL-${cacheIndex}`, parameters.ttl)"
             @mouseleave="handleDataKeyLeave"
           >
@@ -187,6 +193,7 @@ onUnmounted(() => {
           <dt
             class="data-key"
             :class="{ 'key-highlighted': isKeyHovered(`Stored the response-${cacheIndex}`) }"
+            :title="formatTooltip(getFieldTooltip('stored-response'))"
             @mouseenter="handleDataKeyHover(`Stored the response-${cacheIndex}`, parameters.stored)"
             @mouseleave="handleDataKeyLeave"
           >
@@ -208,6 +215,7 @@ onUnmounted(() => {
           <dt
             class="data-key"
             :class="{ 'key-highlighted': isKeyHovered(`Collapsed w/ other reqs-${cacheIndex}`) }"
+            :title="formatTooltip(getFieldTooltip('collapsed-requests'))"
             @mouseenter="handleDataKeyHover(`Collapsed w/ other reqs-${cacheIndex}`, parameters.collapsed)"
             @mouseleave="handleDataKeyLeave"
           >
@@ -229,6 +237,7 @@ onUnmounted(() => {
           <dt
             class="data-key"
             :class="{ 'key-highlighted': isKeyHovered(`Cache key-${cacheIndex}`) }"
+            :title="formatTooltip(getFieldTooltip('cache-key'))"
             @mouseenter="handleDataKeyHover(`Cache key-${cacheIndex}`, parameters.key)"
             @mouseleave="handleDataKeyLeave"
           >
@@ -250,6 +259,7 @@ onUnmounted(() => {
           <dt
             class="data-key"
             :class="{ 'key-highlighted': isKeyHovered(`Extra details-${cacheIndex}`) }"
+            :title="formatTooltip(getFieldTooltip('extra-details'))"
             @mouseenter="handleDataKeyHover(`Extra details-${cacheIndex}`, parameters.detail)"
             @mouseleave="handleDataKeyLeave"
           >
@@ -280,6 +290,7 @@ onUnmounted(() => {
       <dt
         class="data-key"
         :class="{ 'key-highlighted': isKeyHovered('Cacheable') }"
+        :title="formatTooltip(getFieldTooltip('cacheable'))"
         @mouseenter="handleDataKeyHover('Cacheable', cacheAnalysis.cacheControl.isCacheable)"
         @mouseleave="handleDataKeyLeave"
       >
@@ -300,6 +311,7 @@ onUnmounted(() => {
         <dt
           class="data-key"
           :class="{ 'key-highlighted': isKeyHovered('Age') }"
+          :title="formatTooltip(getFieldTooltip('age'))"
           @mouseenter="handleDataKeyHover('Age', cacheAnalysis.cacheControl.age)"
           @mouseleave="handleDataKeyLeave"
         >
@@ -328,6 +340,7 @@ onUnmounted(() => {
         <dt
           class="data-key"
           :class="{ 'key-highlighted': isKeyHovered('Date') }"
+          :title="formatTooltip(getFieldTooltip('date'))"
           @mouseenter="handleDataKeyHover('Date', cacheAnalysis.cacheControl.date)"
           @mouseleave="handleDataKeyLeave"
         >
@@ -355,6 +368,7 @@ onUnmounted(() => {
         <dt
           class="data-key"
           :class="{ 'key-highlighted': isKeyHovered('ETag') }"
+          :title="formatTooltip(getFieldTooltip('etag'))"
           @mouseenter="handleDataKeyHover('ETag', cacheAnalysis.cacheControl.etag)"
           @mouseleave="handleDataKeyLeave"
         >
@@ -376,6 +390,7 @@ onUnmounted(() => {
         <dt
           class="data-key"
           :class="{ 'key-highlighted': isKeyHovered('Expires at') }"
+          :title="formatTooltip(getFieldTooltip('expires-at'))"
           @mouseenter="handleDataKeyHover('Expires at', cacheAnalysis.cacheControl.expiresAt)"
           @mouseleave="handleDataKeyLeave"
         >
@@ -403,6 +418,7 @@ onUnmounted(() => {
         <dt
           class="data-key"
           :class="{ 'key-highlighted': isKeyHovered('TTL (browser)') }"
+          :title="formatTooltip(getFieldTooltip('ttl-browser'))"
           @mouseenter="handleDataKeyHover('TTL (browser)', cacheAnalysis.cacheControl.ttl)"
           @mouseleave="handleDataKeyLeave"
         >
@@ -436,6 +452,7 @@ onUnmounted(() => {
         <dt
           class="data-key"
           :class="{ 'key-highlighted': isKeyHovered('TTL (CDN)') }"
+          :title="formatTooltip(getFieldTooltip('ttl-cdn'))"
           @mouseenter="handleDataKeyHover('TTL (CDN)', cacheAnalysis.cacheControl.cdnTtl)"
           @mouseleave="handleDataKeyLeave"
         >
@@ -468,6 +485,7 @@ onUnmounted(() => {
         <dt
           class="data-key"
           :class="{ 'key-highlighted': isKeyHovered('TTL (Netlify CDN)') }"
+          :title="formatTooltip(getFieldTooltip('ttl-netlify-cdn'))"
           @mouseenter="handleDataKeyHover('TTL (Netlify CDN)', cacheAnalysis.cacheControl.netlifyCdnTtl)"
           @mouseleave="handleDataKeyLeave"
         >
@@ -496,6 +514,7 @@ onUnmounted(() => {
         <dt
           class="data-key"
           :class="{ 'key-highlighted': isKeyHovered('Vary') }"
+          :title="formatTooltip(getFieldTooltip('vary'))"
           @mouseenter="handleDataKeyHover('Vary', cacheAnalysis.cacheControl.vary)"
           @mouseleave="handleDataKeyLeave"
         >
@@ -517,6 +536,7 @@ onUnmounted(() => {
         <dt
           class="data-key"
           :class="{ 'key-highlighted': isKeyHovered('Netlify-Vary') }"
+          :title="formatTooltip(getFieldTooltip('netlify-vary'))"
           @mouseenter="handleDataKeyHover('Netlify-Vary', cacheAnalysis.cacheControl.netlifyVary)"
           @mouseleave="handleDataKeyLeave"
         >
@@ -538,6 +558,7 @@ onUnmounted(() => {
         <dt
           class="data-key"
           :class="{ 'key-highlighted': isKeyHovered('Revalidation') }"
+          :title="formatTooltip(getFieldTooltip('revalidation'))"
           @mouseenter="handleDataKeyHover('Revalidation', cacheAnalysis.cacheControl.revalidate)"
           @mouseleave="handleDataKeyLeave"
         >
diff --git a/app/utils/tooltips.ts b/app/utils/tooltips.ts
new file mode 100644
index 0000000..d39277c
--- /dev/null
+++ b/app/utils/tooltips.ts
@@ -0,0 +1,172 @@
+/**
+ * Tooltip definitions for cache analysis fields
+ */
+
+export interface TooltipDefinition {
+  text: string
+  url?: string
+}
+
+// RFC 9211 forward reason definitions
+const FORWARD_REASONS: Record<string, TooltipDefinition> = {
+  'bypass': {
+    text: 'The cache was configured to not store this response or to not use a stored response for this request.',
+  },
+  'method': {
+    text: 'The request method was such that a cache is not allowed to store a response.',
+  },
+  'uri-miss': {
+    text: 'The cache did not have a stored response for this request URI.',
+  },
+  'vary-miss': {
+    text: 'The cache had a stored response for this request URI, but it could not be used because the Vary header field(s) differed.',
+  },
+  'miss': {
+    text: 'The cache did not have a stored response that could be used for this request.',
+  },
+  'request': {
+    text: 'The request included a cache directive (e.g., no-cache) that prevented the cache from returning a stored response.',
+  },
+  'stale': {
+    text: 'The cache had a stored response that was stale (expired).',
+  },
+  'partial': {
+    text: 'The cache responded with a partial stored response.',
+  },
+}
+
+// Cache name specific tooltips
+const CACHE_NAME_TOOLTIPS: Record<string, TooltipDefinition> = {
+  'Netlify Edge': {
+    text: 'Netlify\'s global edge cache layer that serves cached content from locations closest to users.',
+    url: 'https://docs.netlify.com/platform/caching/',
+  },
+  'Netlify Durable': {
+    text: 'Netlify\'s persistent cache layer that stores content for longer periods, typically used for less frequently accessed resources.',
+    url: 'https://docs.netlify.com/platform/caching/',
+  },
+  'Next.js': {
+    text: 'Next.js application-level caching system that caches rendered pages and API responses.',
+    url: 'https://nextjs.org/docs/app/guides/caching#full-route-cache',
+  },
+}
+
+// General field tooltips
+export const FIELD_TOOLTIPS: Record<string, TooltipDefinition> = {
+  'served-by': {
+    text: 'The service or component that ultimately served this response to the user.',
+  },
+  'cdn-nodes': {
+    text: 'The specific CDN node(s) that handled this request, identified by unique node IDs.',
+  },
+  'hit': {
+    text: 'Whether this cache layer had a stored response that could be used for this request.',
+  },
+  'forwarded-because': {
+    text: 'The reason why this cache layer forwarded the request instead of serving a cached response.',
+  },
+  'forwarded-status': {
+    text: 'The HTTP status code returned when the cache forwarded the request.',
+  },
+  'ttl': {
+    text: 'Time To Live - how long this response can be cached before it expires.',
+  },
+  'stored-response': {
+    text: 'Whether this cache layer stored the response for future use.',
+  },
+  'collapsed-requests': {
+    text: 'Whether multiple identical requests were collapsed into a single request to reduce server load.',
+  },
+  'cache-key': {
+    text: 'The unique identifier used by the cache to store and retrieve this response.',
+  },
+  'extra-details': {
+    text: 'Additional implementation-specific details about how this cache layer handled the request.',
+  },
+  'cacheable': {
+    text: 'Whether this response is allowed to be cached based on its headers and HTTP method.',
+  },
+  'age': {
+    text: 'How long this response has been cached, in seconds since it was first stored.',
+  },
+  'date': {
+    text: 'The timestamp when this response was originally generated by the server.',
+  },
+  'etag': {
+    text: 'A unique identifier for this version of the resource, used for conditional requests and validation.',
+  },
+  'expires-at': {
+    text: 'The specific date and time when this cached response will expire.',
+  },
+  'ttl-browser': {
+    text: 'How long browsers are allowed to cache this response before revalidating.',
+  },
+  'ttl-cdn': {
+    text: 'How long CDN servers are allowed to cache this response before revalidating.',
+  },
+  'ttl-netlify-cdn': {
+    text: 'How long Netlify\'s CDN specifically is allowed to cache this response.',
+  },
+  'vary': {
+    text: 'Headers that determine cache variations - responses will be cached separately based on these header values.',
+  },
+  'netlify-vary': {
+    text: 'Netlify-specific header variations that create separate cache entries based on these values.',
+    url: 'https://docs.netlify.com/platform/caching/#cache-key-variation',
+  },
+  'revalidation': {
+    text: 'Cache revalidation directives that control when and how cached responses should be refreshed.',
+  },
+}
+
+/**
+ * Get tooltip for a cache name, with special handling for known cache types
+ */
+export function getCacheNameTooltip(cacheName: string): TooltipDefinition {
+  const tooltip = CACHE_NAME_TOOLTIPS[cacheName]
+  if (tooltip) {
+    return tooltip
+  }
+
+  return {
+    text: `Third-party cache layer "${cacheName}" along the request path that can store and serve cached responses.`,
+  }
+}
+
+/**
+ * Get tooltip for a forward reason value
+ */
+export function getForwardReasonTooltip(reason: string): TooltipDefinition {
+  const tooltip = FORWARD_REASONS[reason]
+  if (tooltip) {
+    return tooltip
+  }
+
+  return {
+    text: `Cache forwarding reason: ${reason}`,
+  }
+}
+
+/**
+ * Get tooltip for a field, with fallback for unknown fields
+ */
+export function getFieldTooltip(fieldKey: string): TooltipDefinition {
+  const tooltip = FIELD_TOOLTIPS[fieldKey]
+  if (tooltip) {
+    return tooltip
+  }
+
+  return {
+    text: `Information about ${fieldKey}`,
+  }
+}
+
+/**
+ * Create a tooltip string with optional URL for links
+ */
+export function formatTooltip(definition: TooltipDefinition): string {
+  if (definition.url) {
+    return `${definition.text}\n\nLearn more: ${definition.url}`
+  }
+  return definition.text
+}

From b329e545488bbe161a85f9260fdf915e500c354b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 2 Jul 2025 00:03:46 +0000
Subject: [PATCH 3/3] Add comprehensive tooltip tests and finalize
 implementation

Co-authored-by: serhalp <1377702+serhalp@users.noreply.github.com>
---
 app/utils/tooltips.test.ts | 97 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 app/utils/tooltips.test.ts

diff --git a/app/utils/tooltips.test.ts b/app/utils/tooltips.test.ts
new file mode 100644
index 0000000..75712fb
--- /dev/null
+++ b/app/utils/tooltips.test.ts
@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest'
+import { getCacheNameTooltip, getForwardReasonTooltip, getFieldTooltip, formatTooltip } from '~/utils/tooltips'
+
+describe('tooltip utilities', () => {
+  describe('getCacheNameTooltip', () => {
+    it('returns specific tooltip for Netlify Edge', () => {
+      const tooltip = getCacheNameTooltip('Netlify Edge')
+      expect(tooltip.text).toContain('Netlify\'s global edge cache layer')
+      expect(tooltip.url).toBe('https://docs.netlify.com/platform/caching/')
+    })
+
+    it('returns specific tooltip for Netlify Durable', () => {
+      const tooltip = getCacheNameTooltip('Netlify Durable')
+      expect(tooltip.text).toContain('Netlify\'s persistent cache layer')
+      expect(tooltip.url).toBe('https://docs.netlify.com/platform/caching/')
+    })
+
+    it('returns specific tooltip for Next.js', () => {
+      const tooltip = getCacheNameTooltip('Next.js')
+      expect(tooltip.text).toContain('Next.js application-level caching')
+      expect(tooltip.url).toBe('https://nextjs.org/docs/app/guides/caching#full-route-cache')
+    })
+
+    it('returns generic tooltip for unknown cache names', () => {
+      const tooltip = getCacheNameTooltip('Unknown Cache')
+      expect(tooltip.text).toContain('Third-party cache layer "Unknown Cache"')
+      expect(tooltip.url).toBeUndefined()
+    })
+  })
+
+  describe('getForwardReasonTooltip', () => {
+    it('returns specific tooltip for bypass', () => {
+      const tooltip = getForwardReasonTooltip('bypass')
+      expect(tooltip.text).toContain('The cache was configured to not store')
+    })
+
+    it('returns specific tooltip for method', () => {
+      const tooltip = getForwardReasonTooltip('method')
+      expect(tooltip.text).toContain('The request method was such that')
+    })
+
+    it('returns specific tooltip for uri-miss', () => {
+      const tooltip = getForwardReasonTooltip('uri-miss')
+      expect(tooltip.text).toContain('The cache did not have a stored response for this request URI')
+    })
+
+    it('returns specific tooltip for vary-miss', () => {
+      const tooltip = getForwardReasonTooltip('vary-miss')
+      expect(tooltip.text).toContain('Vary header field(s) differed')
+    })
+
+    it('returns generic tooltip for unknown forward reasons', () => {
+      const tooltip = getForwardReasonTooltip('unknown-reason')
+      expect(tooltip.text).toContain('Cache forwarding reason: unknown-reason')
+    })
+  })
+
+  describe('getFieldTooltip', () => {
+    it('returns specific tooltip for served-by', () => {
+      const tooltip = getFieldTooltip('served-by')
+      expect(tooltip.text).toContain('The service or component that ultimately served')
+    })
+
+    it('returns specific tooltip for cdn-nodes', () => {
+      const tooltip = getFieldTooltip('cdn-nodes')
+      expect(tooltip.text).toContain('The specific CDN node(s) that handled this request')
+    })
+
+    it('returns specific tooltip for netlify-vary with URL', () => {
+      const tooltip = getFieldTooltip('netlify-vary')
+      expect(tooltip.text).toContain('Netlify-specific header variations')
+      expect(tooltip.url).toBe('https://docs.netlify.com/platform/caching/#cache-key-variation')
+    })
+
+    it('returns generic tooltip for unknown fields', () => {
+      const tooltip = getFieldTooltip('unknown-field')
+      expect(tooltip.text).toContain('Information about unknown-field')
+    })
+  })
+
+  describe('formatTooltip', () => {
+    it('formats tooltip without URL', () => {
+      const tooltip = { text: 'Simple tooltip text' }
+      const formatted = formatTooltip(tooltip)
+      expect(formatted).toBe('Simple tooltip text')
+    })
+
+    it('formats tooltip with URL', () => {
+      const tooltip = {
+        text: 'Tooltip text with link',
+        url: 'https://example.com',
+      }
+      const formatted = formatTooltip(tooltip)
+      expect(formatted).toBe('Tooltip text with link\n\nLearn more: https://example.com')
+    })
+  })
+})