feat(js): Show which steps a selected framework changes

After a framework is selected, a line under the dropdown names the steps
that changed and links to them. Each changed block gets a "For <framework>"
label, a left border and a short highlight, so the change is visible and
Ctrl+F finds the framework name. The API route now returns a `changed`
flag, so blocks that are the same as without a framework are not marked.

The default entry is now "No framework", and the dropdown uses the same
arrow icon as the sidebar platform selector.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: JPeer264

app/api/platform-content/[platform]/[runtime]/[framework]/[...includePath]/route.ts

@@ -108,6 +108,23 @@ async function collectNested(
   }
 }
 
+async function buildPayload(
+  includePath: string,
+  resolve: (includePath: string) => Promise<SlugFile | undefined>
+): Promise<PlatformContentPayload> {
+  const doc = await resolve(includePath);
+  const payload: PlatformContentPayload = {
+    changed: false,
+    code: doc?.mdxSource ?? null,
+    includes: {},
+    platformContents: {},
+  };
+  if (doc) {
+    await collectNested(doc.matter.content, resolve, payload);
+  }
+  return payload;
+}
+
 export async function GET(
   _request: Request,
   {
@@ -125,16 +142,20 @@ export async function GET(
   const resolve = (path: string) =>
     resolveForFramework(path, platform, runtime, framework);
 
-  const doc = await resolve(includePath.join('/'));
+  const resolveForRuntime = (path: string) =>
+    resolvePlatformContent({
+      includePath: path,
+      path: ['platforms', platform, 'guides', runtime],
+    });
 
-  const payload: PlatformContentPayload = {
-    code: doc?.mdxSource ?? null,
-    includes: {},
-    platformContents: {},
-  };
-  if (doc) {
-    await collectNested(doc.matter.content, resolve, payload);
-  }
+  const [payload, runtimePayload] = await Promise.all([
+    buildPayload(includePath.join('/'), resolve),
+    buildPayload(includePath.join('/'), resolveForRuntime),
+  ]);
+  payload.changed =
+    payload.code !== runtimePayload.code ||
+    JSON.stringify(payload.platformContents) !==
+      JSON.stringify(runtimePayload.platformContents);
 
   return Response.json(payload);
 }

src/components/frameworkSelector/frameworks.ts

@@ -113,6 +113,8 @@ export const FRAMEWORK_QUERY_PARAM = 'framework';
 
 /** The serialized form of a `<PlatformContent>` include, served by the platform-content API route. */
 export type PlatformContentPayload = {
+  /** Whether the content differs from what the runtime's page shows without a framework. */
+  changed: boolean;
   /** Compiled MDX of the resolved include, or `null` if there is no content for it. */
   code: string | null;
   /** Compiled MDX of nested `<Include name="...">` files, keyed by name. */

src/components/frameworkSelector/index.tsx

@@ -1,9 +1,18 @@
 'use client';
 
-import {ArrowRightIcon, ChevronDownIcon} from '@radix-ui/react-icons';
+import {ArrowRightIcon, CaretSortIcon} from '@radix-ui/react-icons';
 import * as RadixSelect from '@radix-ui/react-select';
 import {useRouter} from 'next/navigation';
-import {createContext, ReactNode, useContext, useEffect, useMemo, useState} from 'react';
+import {
+  createContext,
+  ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import {getMDXComponent} from 'sentry-docs/getMDXComponent';
 
 import {Alert} from '../alert';
@@ -28,14 +37,23 @@ import {
   platformContentUrl,
   RUNTIMES,
 } from './frameworks';
+import frameworkStyles from './style.module.scss';
 
 const DEFAULT_VALUE = 'none';
 const GUIDE_VALUE_PREFIX = 'guide:';
 const groupLabelClassName = 'px-2 pt-2 pb-1 text-xs font-medium text-[var(--gray-11)]';
 
+/** The state of a switchable block while a framework is selected. */
+type ContentStatus =
+  | {state: 'loading' | 'unchanged'}
+  /** `step` is the title of the `h2` step that contains the block, `targetId` the block's id. */
+  | {state: 'changed'; targetId: string; step?: string};
+
 type FrameworkContextValue = {
   framework: Framework | null;
   platform: string;
+  /** Records the status of the block with `includePath`, or removes it with `null`. */
+  reportContent: (includePath: string, status: ContentStatus | null) => void;
   /** The runtime guide the page belongs to, e.g. `node`. */
   runtime: string;
 };
@@ -56,6 +74,65 @@ function ItemLabel({icon, title}: {icon: string; title: string}) {
   );
 }
 
+function stepTitle(el: HTMLElement): string | undefined {
+  const step = Array.from(document.querySelectorAll<HTMLElement>('main h2[id]'))
+    .filter(h => h.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING)
+    .pop();
+  return (step?.querySelector('a') ?? step)?.textContent?.trim();
+}
+
+function FrameworkSummary({
+  contents,
+  framework,
+  platform,
+}: {
+  contents: Record<string, ContentStatus>;
+  framework: Framework;
+  platform: string;
+}) {
+  const statuses = Object.values(contents);
+  if (statuses.some(c => c.state === 'loading')) {
+    return (
+      <p className={frameworkStyles.summary}>Loading the steps for {framework.title}…</p>
+    );
+  }
+
+  const changed = statuses
+    .filter(c => c.state === 'changed')
+    .map(c => ({...c, el: document.getElementById(c.targetId)}))
+    .filter(c => c.el)
+    .sort((a, b) =>
+      a.el!.compareDocumentPosition(b.el!) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1
+    );
+  const steps = changed.filter(
+    (c, i) => changed.findIndex(other => other.step === c.step) === i
+  );
+
+  return (
+    <p className={frameworkStyles.summary}>
+      <PlatformIcon
+        platform={`${platform}-${framework.key}`}
+        size={16}
+        format="sm"
+        className="!border-none !shadow-none"
+      />
+      {steps.length > 0 ? (
+        <span>
+          Updated for {framework.title}:{' '}
+          {steps.map((c, i) => (
+            <span key={c.targetId}>
+              {i > 0 && ', '}
+              <a href={`#${c.targetId}`}>{c.step ?? 'Show the change'}</a>
+            </span>
+          ))}
+        </span>
+      ) : (
+        <span>The steps for {framework.title} are the same as without a framework.</span>
+      )}
+    </p>
+  );
+}
+
 function readFrameworkFromUrl(frameworks: Framework[]): Framework | null {
   const key = new URLSearchParams(window.location.search).get(FRAMEWORK_QUERY_PARAM);
   return frameworks.find(f => f.key === key) ?? null;
@@ -90,6 +167,21 @@ export function FrameworkSelector({
   const frameworks = useMemo(() => runtimeConfig?.frameworks ?? [], [runtimeConfig]);
   const frameworkGuides = runtimeConfig?.frameworkGuides ?? [];
   const [framework, setFramework] = useState<Framework | null>(null);
+  const [contents, setContents] = useState<Record<string, ContentStatus>>({});
+
+  const reportContent = useCallback(
+    (includePath: string, status: ContentStatus | null) =>
+      setContents(prev => {
+        const next = {...prev};
+        if (status) {
+          next[includePath] = status;
+        } else {
+          delete next[includePath];
+        }
+        return next;
+      }),
+    []
+  );
 
   // The page is statically rendered, so the query param can only be read after mount.
   useEffect(() => {
@@ -107,8 +199,8 @@ export function FrameworkSelector({
   };
 
   const contextValue = useMemo(
-    () => ({framework, platform, runtime}),
-    [framework, platform, runtime]
+    () => ({framework, platform, reportContent, runtime}),
+    [framework, platform, reportContent, runtime]
   );
 
   return (
@@ -129,7 +221,7 @@ export function FrameworkSelector({
             >
               <RadixSelect.Value />
               <RadixSelect.Icon>
-                <ChevronDownIcon />
+                <CaretSortIcon />
               </RadixSelect.Icon>
             </RadixSelect.Trigger>
             <RadixSelect.Content
@@ -139,10 +231,7 @@ export function FrameworkSelector({
             >
               <RadixSelect.Item value={DEFAULT_VALUE} className={styles.item}>
                 <RadixSelect.ItemText>
-                  <ItemLabel
-                    icon={`${platform}-${runtime}`}
-                    title={`None (plain ${runtimeConfig?.title ?? runtime})`}
-                  />
+                  <ItemLabel icon={`${platform}-${runtime}`} title="No framework" />
                 </RadixSelect.ItemText>
               </RadixSelect.Item>
               {frameworks.length > 0 && (
@@ -182,6 +271,9 @@ export function FrameworkSelector({
           </RadixSelect.Root>
         </div>
       </div>
+      {framework && (
+        <FrameworkSummary contents={contents} framework={framework} platform={platform} />
+      )}
       {children}
     </FrameworkContext.Provider>
   );
@@ -294,18 +386,40 @@ function RemoteFrameworkContent({
   framework,
   includePath,
   platform,
+  reportContent,
   runtime,
 }: {
   fallback: ReactNode;
   framework: Framework;
   includePath: string;
   platform: string;
+  reportContent: FrameworkContextValue['reportContent'];
   runtime: string;
 }) {
   const url = platformContentUrl(platform, runtime, framework.key, includePath);
   const [payload, setPayload] = useState<PlatformContentPayload | null>(null);
   const [error, setError] = useState(false);
   const codeContext = useContext(CodeContext);
+  const changedRef = useRef<HTMLDivElement>(null);
+  const targetId = `framework-content-${includePath.replace(/\//g, '-')}`;
+
+  useEffect(() => {
+    if (error) {
+      reportContent(includePath, {state: 'unchanged'});
+    } else if (!payload) {
+      reportContent(includePath, {state: 'loading'});
+    } else if (!payload.changed || !changedRef.current) {
+      reportContent(includePath, {state: 'unchanged'});
+    } else {
+      reportContent(includePath, {
+        state: 'changed',
+        step: stepTitle(changedRef.current),
+        targetId,
+      });
+    }
+  }, [error, includePath, payload, reportContent, targetId]);
+
+  useEffect(() => () => reportContent(includePath, null), [includePath, reportContent]);
 
   useEffect(() => {
     let cancelled = false;
@@ -333,7 +447,7 @@ function RemoteFrameworkContent({
     }
   }, [payload, codeContext?.onboardingOptions]);
 
-  if (error) {
+  if (error || payload?.changed === false) {
     return fallback;
   }
 
@@ -345,7 +459,20 @@ function RemoteFrameworkContent({
     );
   }
 
-  return <mdx.MDX code={payload.code} />;
+  return (
+    <div key={url} ref={changedRef} id={targetId} className={frameworkStyles.changed}>
+      <p className={frameworkStyles.label}>
+        <PlatformIcon
+          platform={`${platform}-${framework.key}`}
+          size={16}
+          format="sm"
+          className="!border-none !shadow-none"
+        />
+        For {framework.title}
+      </p>
+      <mdx.MDX code={payload.code} />
+    </div>
+  );
 }
 
 /**
@@ -371,6 +498,7 @@ export function FrameworkContent({
       framework={context.framework}
       includePath={includePath}
       platform={context.platform}
+      reportContent={context.reportContent}
       runtime={context.runtime}
     />
   );

src/components/frameworkSelector/style.module.scss

@@ -0,0 +1,40 @@
+.summary {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-top: -0.5rem;
+  font-size: 0.875rem;
+  color: var(--gray-11);
+}
+
+.changed {
+  margin-block: 1rem;
+  padding: 0.25rem 0 0.25rem 1rem;
+  border-left: 3px solid var(--accent-purple);
+  border-radius: 0 0.25rem 0.25rem 0;
+  // Clears the sticky header and the sticky feature buttons of the quick start
+  scroll-margin-top: calc(var(--header-height) + 5rem);
+  animation: highlight 1.6s ease-out;
+}
+
+.label {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin: 0 0 0.5rem;
+  font-size: 0.75rem;
+  font-weight: 500;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--accent-purple);
+}
+
+@keyframes highlight {
+  from {
+    background-color: var(--accent-purple-light);
+  }
+
+  to {
+    background-color: transparent;
+  }
+}