From b9ea6038507d4620b64d9aef99616ae46316855b Mon Sep 17 00:00:00 2001
From: Gert Hengeveld <info@ghengeveld.nl>
Date: Tue, 26 May 2026 22:36:05 +0200
Subject: [PATCH 01/14] Add a baseline-vs-latest comparison experience to the
 review details screen with 1up/2up modes, view toggles, and readiness gating
 so latest stays visible while baseline loads. Also proxy baseline previews
 through a local __review-baseline dev-server route and keep the two iframes
 aligned by syncing URL and scroll position.

---
 code/addons/review/package.json               |   1 +
 code/addons/review/src/preset.ts              |  18 +-
 .../src/screens/DetailsScreen.stories.tsx     |  20 +-
 .../review/src/screens/DetailsScreen.tsx      | 415 +++++++++++++++---
 code/core/src/manager/settings/GuidePage.tsx  |   2 +-
 yarn.lock                                     |  65 ++-
 6 files changed, 434 insertions(+), 87 deletions(-)

diff --git a/code/addons/review/package.json b/code/addons/review/package.json
index 3252237856d7..3436641e426f 100644
--- a/code/addons/review/package.json
+++ b/code/addons/review/package.json
@@ -42,6 +42,7 @@
     "!src/**/*"
   ],
   "devDependencies": {
+    "http-proxy-middleware": "^4.0.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "typescript": "^5.9.3"
diff --git a/code/addons/review/src/preset.ts b/code/addons/review/src/preset.ts
index 81bed879c5f4..82e6b6bd75c3 100644
--- a/code/addons/review/src/preset.ts
+++ b/code/addons/review/src/preset.ts
@@ -1,5 +1,6 @@
+import { createProxyMiddleware } from 'http-proxy-middleware';
 import type { Channel } from 'storybook/internal/channels';
-import type { Options } from 'storybook/internal/types';
+import type { Middleware, Options, ServerApp } from 'storybook/internal/types';
 
 import { EVENTS } from './constants.ts';
 import type { ReviewState } from './review-state.ts';
@@ -70,3 +71,18 @@ export const experimental_serverChannel = async (
 
   return channel;
 };
+
+const BASELINE_PROXY_PATH = '/__review-baseline';
+const BASELINE_TARGET_ORIGIN = 'https://next--635781f3500dd2c49e189caf.chromatic.com';
+
+export const experimental_devServer = (app: ServerApp) => {
+  const proxyRequest = createProxyMiddleware({
+    target: BASELINE_TARGET_ORIGIN,
+    changeOrigin: true,
+    pathRewrite: (path) =>
+      path.startsWith(BASELINE_PROXY_PATH) ? path.slice(BASELINE_PROXY_PATH.length) || '/' : path,
+  }) as unknown as Middleware;
+
+  app.use(BASELINE_PROXY_PATH, proxyRequest);
+  return app;
+};
diff --git a/code/addons/review/src/screens/DetailsScreen.stories.tsx b/code/addons/review/src/screens/DetailsScreen.stories.tsx
index 30254b5555e5..5a91609039b1 100644
--- a/code/addons/review/src/screens/DetailsScreen.stories.tsx
+++ b/code/addons/review/src/screens/DetailsScreen.stories.tsx
@@ -11,10 +11,10 @@ const meta = preview.meta({
   component: DetailsScreen,
   parameters: { layout: 'fullscreen' },
   args: {
-    title: 'Toolbar',
-    componentTitle: 'Manager/Components/Toolbar',
-    storyName: 'Basic',
-    storyId: 'components-toolbar--basic',
+    title: 'Guide Page',
+    componentTitle: 'Manager/Settings/GuidePage',
+    storyName: 'Default',
+    storyId: 'manager-settings-guidepage--default',
     storyIndex: 1,
     totalStories: 3,
     backHref: buildReviewChangesSummaryHref(),
@@ -28,7 +28,6 @@ const meta = preview.meta({
       collectionIndex: 0,
       storyId: 'components-toolbar--dense',
     }),
-    branchName: 'update/button-weight-and-padding',
   },
 });
 
@@ -36,17 +35,20 @@ export const Default = meta.story({
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
     await expect(await canvas.findByRole('button', { name: '2/3' })).toBeInTheDocument();
-    await expect(await canvas.findByText('Toolbar')).toBeInTheDocument();
-    await expect(await canvas.findByText('Basic')).toBeInTheDocument();
+    await expect(await canvas.findByText('GuidePage')).toBeInTheDocument();
+    await expect(await canvas.findByText('Default')).toBeInTheDocument();
     await expect(
-      await canvas.findByText('Latest on update/button-weight-and-padding')
+      await canvas.findByTitle('Baseline manager-settings-guidepage--default')
+    ).toBeInTheDocument();
+    await expect(
+      await canvas.findByTitle('Latest manager-settings-guidepage--default')
     ).toBeInTheDocument();
   },
 });
 
 export const WrapAroundNavigation = meta.story({
   args: {
-    storyId: 'components-toolbar--basic',
+    storyId: 'manager-settings-guidepage--default',
     storyIndex: 0,
     totalStories: 3,
     previousHref: buildReviewChangesDetailHref({
diff --git a/code/addons/review/src/screens/DetailsScreen.tsx b/code/addons/review/src/screens/DetailsScreen.tsx
index d21fab97b4df..6382fc7a2133 100644
--- a/code/addons/review/src/screens/DetailsScreen.tsx
+++ b/code/addons/review/src/screens/DetailsScreen.tsx
@@ -1,9 +1,16 @@
-import React, { type FC } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 
 import { Button } from 'storybook/internal/components';
+import { STORY_RENDERED } from 'storybook/internal/core-events';
 import { styled } from 'storybook/theming';
 
-import { ChevronSmallLeftIcon, ChevronSmallRightIcon } from '@storybook/icons';
+import {
+  CategoryIcon,
+  ChevronSmallLeftIcon,
+  ChevronSmallRightIcon,
+  SideBySideIcon,
+  TransferIcon,
+} from '@storybook/icons';
 
 const Page = styled.div(({ theme }) => ({
   display: 'flex',
@@ -57,12 +64,49 @@ const DetailTitleRegular = styled.span({
   fontWeight: 400,
 });
 
-const PreviewFrameWrap = styled.div({
+type PreviewMode = '1up' | '2up';
+type VisibleSide = 'baseline' | 'latest';
+
+const PreviewFrameWrap = styled.div<{ $singleUp: boolean }>(({ $singleUp }) => ({
   flex: 1,
   minHeight: 0,
   width: '100%',
   display: 'flex',
-});
+  position: 'relative',
+  ...($singleUp ? { overflow: 'hidden' } : {}),
+}));
+
+const PreviewPane = styled.div<{ $singleUp: boolean; $active: boolean }>(
+  ({ $singleUp, $active }) => ({
+    minWidth: 0,
+    minHeight: 0,
+    display: 'flex',
+    ...($singleUp
+      ? {
+          position: 'absolute',
+          inset: 0,
+          width: '100%',
+          height: '100%',
+          zIndex: $active ? 1 : -1,
+          pointerEvents: $active ? 'auto' : 'none',
+          visibility: $active ? 'visible' : 'hidden',
+        }
+      : {
+          flex: 1,
+          position: 'relative',
+        }),
+  })
+);
+
+const PaneDivider = styled.div(({ theme }) => ({
+  width: 1,
+  flexShrink: 0,
+  background: theme.color.border,
+}));
+
+const PreviewDivider = styled(PaneDivider)<{ $singleUp: boolean }>(({ $singleUp }) => ({
+  display: $singleUp ? 'none' : 'block',
+}));
 
 const PreviewFrame = styled.iframe({
   flex: 1,
@@ -75,25 +119,50 @@ const PreviewFrame = styled.iframe({
 const BottomToolbar = styled.div(({ theme }) => ({
   display: 'flex',
   alignItems: 'center',
-  justifyContent: 'space-between',
-  gap: 6,
   minHeight: 40,
-  padding: '0 10px 0 16px',
   borderTop: `1px solid ${theme.appBorderColor}`,
 }));
 
-const BranchText = styled.div({
+const BottomHalf = styled.div({
+  flex: 1,
+  minWidth: 0,
+  height: '100%',
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'flex-start',
+  padding: '0 16px',
+});
+
+const BottomDivider = styled(PaneDivider)<{ $singleUp: boolean }>(({ $singleUp }) => ({
+  display: $singleUp ? 'none' : 'block',
+}));
+
+const RightBottomHalf = styled(BottomHalf)<{ $singleUp: boolean }>(({ $singleUp }) => ({
+  justifyContent: $singleUp ? 'flex-end' : 'space-between',
+  gap: 8,
+}));
+
+const BottomControls = styled.div({
+  display: 'flex',
+  alignItems: 'center',
+  gap: 4,
+});
+
+const BottomLabel = styled.div({
   fontSize: 13,
   lineHeight: '20px',
   fontWeight: 600,
 });
 
-const BottomRightPlaceholder = styled.div({
-  width: 24,
-  height: 24,
-});
-
+const BASELINE_PROXY_PATH = '/__review-baseline';
 const storyPreviewUrl = (id: string) => `iframe.html?id=${encodeURIComponent(id)}&viewMode=story`;
+const toBaselinePreviewUrl = (latestUrlString: string) => {
+  const latestUrl = new URL(latestUrlString, window.location.href);
+  return new URL(
+    `${BASELINE_PROXY_PATH}${latestUrl.pathname}${latestUrl.search}${latestUrl.hash}`,
+    window.location.origin
+  ).toString();
+};
 
 export interface DetailsScreenProps {
   /** Fallback title shown when story metadata is unavailable. */
@@ -137,7 +206,7 @@ const renderDetailTitle = ({
 // The preview <iframe> is intentionally a stable element: when the story
 // changes the parent only updates `src`, so the iframe navigates in place
 // without the manager (or this component) remounting — no flash.
-export const DetailsScreen: FC<DetailsScreenProps> = ({
+export const DetailsScreen = ({
   title,
   storyId,
   storyIndex,
@@ -147,43 +216,281 @@ export const DetailsScreen: FC<DetailsScreenProps> = ({
   nextHref,
   componentTitle,
   storyName,
-  branchName,
-}) => (
-  <Page>
-    <Toolbar>
-      <ToolbarSide>
-        <Button variant="ghost" size="small" padding="small" ariaLabel="Back to review" asChild>
-          <a href={backHref}>
-            <ChevronSmallLeftIcon />
-          </a>
-        </Button>
-        <DetailTitle>{renderDetailTitle({ title, componentTitle, storyName })}</DetailTitle>
-      </ToolbarSide>
-
-      <ToolbarSide>
-        <Button variant="ghost" size="small" readOnly>
-          {storyIndex + 1}/{totalStories}
-        </Button>
-        <Button variant="ghost" size="small" padding="small" ariaLabel="Previous story" asChild>
-          <a href={previousHref}>
-            <ChevronSmallLeftIcon />
-          </a>
-        </Button>
-        <Button variant="ghost" size="small" padding="small" ariaLabel="Next story" asChild>
-          <a href={nextHref}>
-            <ChevronSmallRightIcon />
-          </a>
-        </Button>
-      </ToolbarSide>
-    </Toolbar>
-
-    <PreviewFrameWrap>
-      <PreviewFrame title={storyId} src={storyPreviewUrl(storyId)} />
-    </PreviewFrameWrap>
-
-    <BottomToolbar>
-      <BranchText>Latest on {branchName ?? 'this branch'}</BranchText>
-      <BottomRightPlaceholder />
-    </BottomToolbar>
-  </Page>
-);
+}: DetailsScreenProps) => {
+  const latestPreviewSrc = storyPreviewUrl(storyId);
+  const [baselinePreviewSrc, setBaselinePreviewSrc] = useState(() =>
+    toBaselinePreviewUrl(latestPreviewSrc)
+  );
+  const baselinePreviewSrcRef = useRef(baselinePreviewSrc);
+  const [isBaselineReady, setIsBaselineReady] = useState(false);
+  const [previewMode, setPreviewMode] = useState<PreviewMode>('1up');
+  const [visibleSide, setVisibleSide] = useState<VisibleSide>('latest');
+  const isSingleUp = previewMode === '1up';
+  const effectiveVisibleSide = isBaselineReady ? visibleSide : 'latest';
+
+  const baselineFrameRef = useRef<HTMLIFrameElement>(null);
+  const latestFrameRef = useRef<HTMLIFrameElement>(null);
+  const cleanupScrollSyncRef = useRef<(() => void) | null>(null);
+  const cleanupBaselineStoryRenderedRef = useRef<(() => void) | null>(null);
+  const syncingTargetRef = useRef<VisibleSide | null>(null);
+
+  const disableOverscrollBounce = useCallback((frameElement: HTMLIFrameElement | null) => {
+    const iframeDocument = frameElement?.contentDocument;
+    if (!iframeDocument) {
+      return;
+    }
+
+    iframeDocument.documentElement.style.overscrollBehavior = 'none';
+    iframeDocument.documentElement.style.overscrollBehaviorX = 'none';
+    iframeDocument.documentElement.style.overscrollBehaviorY = 'none';
+
+    if (iframeDocument.body) {
+      iframeDocument.body.style.overscrollBehavior = 'none';
+      iframeDocument.body.style.overscrollBehaviorX = 'none';
+      iframeDocument.body.style.overscrollBehaviorY = 'none';
+    }
+  }, []);
+
+  const setupScrollSync = useCallback(() => {
+    cleanupScrollSyncRef.current?.();
+    cleanupScrollSyncRef.current = null;
+
+    disableOverscrollBounce(baselineFrameRef.current);
+    disableOverscrollBounce(latestFrameRef.current);
+
+    const baselineWindow = baselineFrameRef.current?.contentWindow;
+    const latestWindow = latestFrameRef.current?.contentWindow;
+    if (!baselineWindow || !latestWindow) {
+      return;
+    }
+
+    const releaseSyncLock = () => {
+      window.requestAnimationFrame(() => {
+        syncingTargetRef.current = null;
+      });
+    };
+
+    const syncFromBaseline = () => {
+      if (syncingTargetRef.current === 'baseline') {
+        return;
+      }
+      syncingTargetRef.current = 'latest';
+      latestWindow.scrollTo(baselineWindow.scrollX, baselineWindow.scrollY);
+      releaseSyncLock();
+    };
+
+    const syncFromLatest = () => {
+      if (syncingTargetRef.current === 'latest') {
+        return;
+      }
+      syncingTargetRef.current = 'baseline';
+      baselineWindow.scrollTo(latestWindow.scrollX, latestWindow.scrollY);
+      releaseSyncLock();
+    };
+
+    baselineWindow.addEventListener('scroll', syncFromBaseline, { passive: true });
+    latestWindow.addEventListener('scroll', syncFromLatest, { passive: true });
+
+    cleanupScrollSyncRef.current = () => {
+      baselineWindow.removeEventListener('scroll', syncFromBaseline);
+      latestWindow.removeEventListener('scroll', syncFromLatest);
+      syncingTargetRef.current = null;
+    };
+  }, [disableOverscrollBounce]);
+
+  useEffect(() => {
+    baselinePreviewSrcRef.current = baselinePreviewSrc;
+  }, [baselinePreviewSrc]);
+
+  useEffect(() => {
+    setIsBaselineReady(false);
+    setBaselinePreviewSrc(toBaselinePreviewUrl(latestPreviewSrc));
+  }, [latestPreviewSrc]);
+
+  useEffect(() => {
+    const baselineFrame = baselineFrameRef.current;
+    const latestFrame = latestFrameRef.current;
+    if (!baselineFrame || !latestFrame) {
+      return;
+    }
+
+    const syncBaselineToLatest = () => {
+      const baselineWindow = baselineFrameRef.current?.contentWindow;
+      const latestWindow = latestFrameRef.current?.contentWindow;
+      if (!baselineWindow || !latestWindow) {
+        return;
+      }
+      baselineWindow.scrollTo(latestWindow.scrollX, latestWindow.scrollY);
+    };
+
+    const attachBaselineStoryRenderedListener = () => {
+      cleanupBaselineStoryRenderedRef.current?.();
+      cleanupBaselineStoryRenderedRef.current = null;
+
+      const baselineChannel = (
+        baselineFrameRef.current?.contentWindow as Window & {
+          __STORYBOOK_ADDONS_CHANNEL__?: {
+            on?: (event: string, listener: () => void) => void;
+            off?: (event: string, listener: () => void) => void;
+            removeListener?: (event: string, listener: () => void) => void;
+          };
+        }
+      ).__STORYBOOK_ADDONS_CHANNEL__;
+
+      if (!baselineChannel?.on) {
+        return;
+      }
+
+      const onBaselineStoryRendered = () => {
+        syncBaselineToLatest();
+        setupScrollSync();
+        cleanupBaselineStoryRenderedRef.current?.();
+      };
+
+      cleanupBaselineStoryRenderedRef.current = () => {
+        if (baselineChannel.off) {
+          baselineChannel.off(STORY_RENDERED, onBaselineStoryRendered);
+        } else if (baselineChannel.removeListener) {
+          baselineChannel.removeListener(STORY_RENDERED, onBaselineStoryRendered);
+        }
+        cleanupBaselineStoryRenderedRef.current = null;
+      };
+
+      baselineChannel.on(STORY_RENDERED, onBaselineStoryRendered);
+    };
+
+    const handleBaselineFrameLoad = () => {
+      setIsBaselineReady(true);
+      attachBaselineStoryRenderedListener();
+      setupScrollSync();
+    };
+
+    const handleLatestFrameLoad = () => {
+      const latestLocationHref = latestFrameRef.current?.contentWindow?.location.href;
+      if (latestLocationHref) {
+        const nextBaselineUrl = toBaselinePreviewUrl(latestLocationHref);
+        if (baselinePreviewSrcRef.current !== nextBaselineUrl) {
+          setIsBaselineReady(false);
+          setBaselinePreviewSrc(nextBaselineUrl);
+        }
+      }
+      setupScrollSync();
+    };
+
+    baselineFrame.addEventListener('load', handleBaselineFrameLoad);
+    latestFrame.addEventListener('load', handleLatestFrameLoad);
+    setupScrollSync();
+
+    return () => {
+      cleanupBaselineStoryRenderedRef.current?.();
+      baselineFrame.removeEventListener('load', handleBaselineFrameLoad);
+      latestFrame.removeEventListener('load', handleLatestFrameLoad);
+      cleanupScrollSyncRef.current?.();
+      cleanupScrollSyncRef.current = null;
+    };
+  }, [setupScrollSync]);
+
+  return (
+    <Page>
+      <Toolbar>
+        <ToolbarSide>
+          <Button variant="ghost" size="small" padding="small" ariaLabel="Back to review" asChild>
+            <a href={backHref}>
+              <ChevronSmallLeftIcon />
+            </a>
+          </Button>
+          <DetailTitle>{renderDetailTitle({ title, componentTitle, storyName })}</DetailTitle>
+        </ToolbarSide>
+
+        <ToolbarSide>
+          <Button variant="ghost" size="small" readOnly>
+            {storyIndex + 1}/{totalStories}
+          </Button>
+          <Button variant="ghost" size="small" padding="small" ariaLabel="Previous story" asChild>
+            <a href={previousHref}>
+              <ChevronSmallLeftIcon />
+            </a>
+          </Button>
+          <Button variant="ghost" size="small" padding="small" ariaLabel="Next story" asChild>
+            <a href={nextHref}>
+              <ChevronSmallRightIcon />
+            </a>
+          </Button>
+        </ToolbarSide>
+      </Toolbar>
+
+      <PreviewFrameWrap $singleUp={isSingleUp}>
+        <PreviewPane
+          $singleUp={isSingleUp}
+          $active={!isSingleUp || effectiveVisibleSide === 'baseline'}
+        >
+          <PreviewFrame
+            ref={baselineFrameRef}
+            title={`Baseline ${storyId}`}
+            src={baselinePreviewSrc}
+          />
+        </PreviewPane>
+        {isSingleUp ? null : <PreviewDivider $singleUp={isSingleUp} />}
+        <PreviewPane
+          $singleUp={isSingleUp}
+          $active={!isSingleUp || effectiveVisibleSide === 'latest'}
+        >
+          <PreviewFrame ref={latestFrameRef} title={`Latest ${storyId}`} src={latestPreviewSrc} />
+        </PreviewPane>
+      </PreviewFrameWrap>
+
+      {isBaselineReady ? (
+        <BottomToolbar>
+          <BottomHalf>
+            <BottomLabel>
+              {isSingleUp
+                ? effectiveVisibleSide === 'baseline'
+                  ? 'Baseline'
+                  : 'Latest'
+                : 'Baseline'}
+            </BottomLabel>
+          </BottomHalf>
+          <BottomDivider $singleUp={isSingleUp} />
+          <RightBottomHalf $singleUp={isSingleUp}>
+            {!isSingleUp ? <BottomLabel>Latest</BottomLabel> : null}
+            <BottomControls>
+              {isSingleUp ? (
+                <Button
+                  variant="ghost"
+                  size="small"
+                  padding="small"
+                  ariaLabel="Swap visible preview"
+                  onClick={() =>
+                    setVisibleSide((current) => (current === 'latest' ? 'baseline' : 'latest'))
+                  }
+                >
+                  <TransferIcon />
+                </Button>
+              ) : null}
+              <Button
+                variant="ghost"
+                size="small"
+                padding="small"
+                ariaLabel="Single preview mode"
+                active={previewMode === '1up'}
+                onClick={() => setPreviewMode('1up')}
+              >
+                <CategoryIcon />
+              </Button>
+              <Button
+                variant="ghost"
+                size="small"
+                padding="small"
+                ariaLabel="Side-by-side preview mode"
+                active={previewMode === '2up'}
+                onClick={() => setPreviewMode('2up')}
+              >
+                <SideBySideIcon />
+              </Button>
+            </BottomControls>
+          </RightBottomHalf>
+        </BottomToolbar>
+      ) : null}
+    </Page>
+  );
+};
diff --git a/code/core/src/manager/settings/GuidePage.tsx b/code/core/src/manager/settings/GuidePage.tsx
index 9dae45ec510b..7584fae8fdc8 100644
--- a/code/core/src/manager/settings/GuidePage.tsx
+++ b/code/core/src/manager/settings/GuidePage.tsx
@@ -43,7 +43,7 @@ export const GuidePage = () => {
   return (
     <Container>
       <Intro>
-        <h1>Guide</h1>
+        <h1>Onboarding guide</h1>
         <p>
           Whether you&apos;re just getting started or looking for ways to level up, this checklist
           will help you make the most of your Storybook.
diff --git a/yarn.lock b/yarn.lock
index bb79710bbcf2..f2d6f24249da 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -8315,6 +8315,7 @@ __metadata:
   version: 0.0.0-use.local
   resolution: "@storybook/addon-review@workspace:code/addons/review"
   dependencies:
+    http-proxy-middleware: "npm:^4.0.0"
     react: "npm:^18.2.0"
     react-dom: "npm:^18.2.0"
     typescript: "npm:^5.9.3"
@@ -9929,8 +9930,8 @@ __metadata:
   linkType: hard
 
 "@tmcp/adapter-valibot@npm:^0.1.5":
-  version: 0.1.5
-  resolution: "@tmcp/adapter-valibot@npm:0.1.5"
+  version: 0.1.6
+  resolution: "@tmcp/adapter-valibot@npm:0.1.6"
   dependencies:
     "@standard-schema/spec": "npm:^1.0.0"
     "@valibot/to-json-schema": "npm:^1.3.0"
@@ -9938,24 +9939,24 @@ __metadata:
   peerDependencies:
     tmcp: ^1.17.0
     valibot: ^1.1.0
-  checksum: 10c0/176be80a74285f986ba8900116bf1ec2b97d249177b48127940b06bd08c70965a2e50d0aaa3785d4bdadd70f8e3f341fd881ce24c317a9d890cdb24ebf059399
+  checksum: 10c0/4261efa7318f335eb7a8787f16a4db285a3e38288c31bc3b21fe61808c7e0c2057e09675d7b86d14cbe3ba2babad2ffe1891c4498001b27f74cb22fa135eef02
   languageName: node
   linkType: hard
 
-"@tmcp/session-manager@npm:^0.2.1":
-  version: 0.2.1
-  resolution: "@tmcp/session-manager@npm:0.2.1"
+"@tmcp/session-manager@npm:^0.2.2":
+  version: 0.2.2
+  resolution: "@tmcp/session-manager@npm:0.2.2"
   peerDependencies:
     tmcp: ^1.16.3
-  checksum: 10c0/dadcfe6cf0e2be2536f0969aab3782355f2ff705d0a782ee9017e644b31c7eb57a593954676c252373a7d042ec6cd026e27db27460085b1c1036f7dcb1b37af5
+  checksum: 10c0/a29507e7e36568f4eb5f0e7525c651adf4ec16d11273499f538f2e5cc4071920294c08cc4771b11cb52bc9f999e3a1a32466bb6521f605fc482cc932139b5d25
   languageName: node
   linkType: hard
 
 "@tmcp/transport-http@npm:^0.8.5":
-  version: 0.8.5
-  resolution: "@tmcp/transport-http@npm:0.8.5"
+  version: 0.8.6
+  resolution: "@tmcp/transport-http@npm:0.8.6"
   dependencies:
-    "@tmcp/session-manager": "npm:^0.2.1"
+    "@tmcp/session-manager": "npm:^0.2.2"
     esm-env: "npm:^1.2.2"
   peerDependencies:
     "@tmcp/auth": ^0.3.3 || ^0.4.0
@@ -9963,7 +9964,7 @@ __metadata:
   peerDependenciesMeta:
     "@tmcp/auth":
       optional: true
-  checksum: 10c0/208ba54571188e69ec57a33cc316ece812f3013c2e5c2355be62cb17e90665b258e069bd7eadce7898612018a7bd0ce958db95357a409930ca7a119a00d3c28e
+  checksum: 10c0/da9a734cf15bcc84527194b2848ebcb33815fb9c26d579a90b2f0052eb193d764c1857f4c172f87167a51339f78cf7e17eba2b15f8a90459158b54a519291527
   languageName: node
   linkType: hard
 
@@ -11302,11 +11303,11 @@ __metadata:
   linkType: hard
 
 "@valibot/to-json-schema@npm:^1.3.0":
-  version: 1.6.0
-  resolution: "@valibot/to-json-schema@npm:1.6.0"
+  version: 1.7.0
+  resolution: "@valibot/to-json-schema@npm:1.7.0"
   peerDependencies:
-    valibot: ^1.3.0
-  checksum: 10c0/3dabbb9ed0f135c436a9f4a22ff1ad3df500e0bdff1b771eb9a03f4ba7a412bb1873a9cc1ff32c09ff47d10be8d1834a540705229380b9fc46fb65a9b41dbae2
+    valibot: ^1.4.0
+  checksum: 10c0/d354217270f5855ceea547bcf696546e30075b04016757603c9e826b4395aefecbd0f8a79bea4431838b28960e09a2b7543aa5c5f8672c9abb2ab7d39354f533
   languageName: node
   linkType: hard
 
@@ -15575,7 +15576,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"debug@npm:4, debug@npm:^4.0.0, debug@npm:^4.1.0, debug@npm:^4.1.1, debug@npm:^4.3.1, debug@npm:^4.3.2, debug@npm:^4.3.4, debug@npm:^4.3.6, debug@npm:^4.3.7, debug@npm:^4.4.0, debug@npm:^4.4.1":
+"debug@npm:4, debug@npm:^4.0.0, debug@npm:^4.1.0, debug@npm:^4.1.1, debug@npm:^4.3.1, debug@npm:^4.3.2, debug@npm:^4.3.4, debug@npm:^4.3.6, debug@npm:^4.3.7, debug@npm:^4.4.0, debug@npm:^4.4.1, debug@npm:^4.4.3":
   version: 4.4.3
   resolution: "debug@npm:4.4.3"
   dependencies:
@@ -20137,6 +20138,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"http-proxy-middleware@npm:^4.0.0":
+  version: 4.0.0
+  resolution: "http-proxy-middleware@npm:4.0.0"
+  dependencies:
+    debug: "npm:^4.4.3"
+    httpxy: "npm:^0.5.1"
+    is-glob: "npm:^4.0.3"
+    is-plain-obj: "npm:^4.1.0"
+    micromatch: "npm:^4.0.8"
+  checksum: 10c0/956cfec006b3619433e5c5ce24e9379bbe2e2ae885705df82c261530392c94c101205ef891845fe7d39b9d646a463c302b3b6d90125dc6e8dc42fbd7c6211c69
+  languageName: node
+  linkType: hard
+
 "http-proxy@npm:^1.18.1":
   version: 1.18.1
   resolution: "http-proxy@npm:1.18.1"
@@ -20234,6 +20248,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"httpxy@npm:^0.5.1":
+  version: 0.5.3
+  resolution: "httpxy@npm:0.5.3"
+  checksum: 10c0/8120753638d1a50b13396d7c55536db076a04609dfb7eea19f5b461f9541acf4646fa6bfb8991f14bad62e0037b524481c5d625892b4ff94a6ab744149ed9387
+  languageName: node
+  linkType: hard
+
 "human-signals@npm:^8.0.1":
   version: 8.0.1
   resolution: "human-signals@npm:8.0.1"
@@ -30670,15 +30691,15 @@ __metadata:
   linkType: hard
 
 "tmcp@npm:^1.19.3":
-  version: 1.19.3
-  resolution: "tmcp@npm:1.19.3"
+  version: 1.19.4
+  resolution: "tmcp@npm:1.19.4"
   dependencies:
     "@standard-schema/spec": "npm:^1.0.0"
     json-rpc-2.0: "npm:^1.7.1"
     sqids: "npm:^0.3.0"
     uri-template-matcher: "npm:^1.1.1"
     valibot: "npm:^1.1.0"
-  checksum: 10c0/c310c21b32aa6716037eebd126eb39a62e86ef99a9d95b8dc53b7e5d212b7109beefa56506a489193018e3caed471809da8d1b07de00e747b259d0396b9b49c3
+  checksum: 10c0/fcb275c74fe4dd80da3eb4702d7631423e73f2dd9ec537228457b997a9206ece899295035a492a9238184e28a46017034f63c6a4aa82d1fe0ee486fb7b33449a
   languageName: node
   linkType: hard
 
@@ -31817,14 +31838,14 @@ __metadata:
   linkType: hard
 
 "valibot@npm:^1.1.0":
-  version: 1.3.1
-  resolution: "valibot@npm:1.3.1"
+  version: 1.4.1
+  resolution: "valibot@npm:1.4.1"
   peerDependencies:
     typescript: ">=5"
   peerDependenciesMeta:
     typescript:
       optional: true
-  checksum: 10c0/e20a4097fa726f57530da1e64558af47ddd2303129c77978fe93c522c66cf4c79540ea3af864523589283ea25e347c3d65b8044fa4913376208dde576b9f6382
+  checksum: 10c0/8a492d9c6d21032abea4fa29eafa355e5c31f1df6a3ba4b207abf20433c00b66b30884f60b225c3348113a327f20bb19e01e9b7771663e462cf94398ff39d233
   languageName: node
   linkType: hard
 

From b677c0ae739b7bbf57adcc01646a7467fcd7ba82 Mon Sep 17 00:00:00 2001
From: Gert Hengeveld <info@ghengeveld.nl>
Date: Thu, 28 May 2026 14:40:51 +0200
Subject: [PATCH 02/14] Fix React import

---
 code/addons/review/src/screens/DetailsScreen.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/code/addons/review/src/screens/DetailsScreen.tsx b/code/addons/review/src/screens/DetailsScreen.tsx
index 6382fc7a2133..19d6b87ab50b 100644
--- a/code/addons/review/src/screens/DetailsScreen.tsx
+++ b/code/addons/review/src/screens/DetailsScreen.tsx
@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
 
 import { Button } from 'storybook/internal/components';
 import { STORY_RENDERED } from 'storybook/internal/core-events';

From 8fffe6ea1aa6c726e6253f373a05edc693360330 Mon Sep 17 00:00:00 2001
From: Gert Hengeveld <info@ghengeveld.nl>
Date: Tue, 2 Jun 2026 18:55:55 +0200
Subject: [PATCH 03/14] Fix review screen story failures

Guard documentElement before setting overscroll styles in DetailsScreen,
since the capture-loopback baseline iframe can expose a document with a
null documentElement, throwing "Cannot read properties of null (reading
'style')" during the Details story.

Update the SummaryScreen Minimal play function to match the current
generic headline ("Showing N agent-curated stories...") instead of the
removed branch-specific text.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../review/src/screens/DetailsScreen.tsx      | 20 +++++++++++--------
 .../src/screens/SummaryScreen.stories.tsx     |  5 +++--
 2 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/code/addons/review/src/screens/DetailsScreen.tsx b/code/addons/review/src/screens/DetailsScreen.tsx
index 19d6b87ab50b..6f40d97c95ca 100644
--- a/code/addons/review/src/screens/DetailsScreen.tsx
+++ b/code/addons/review/src/screens/DetailsScreen.tsx
@@ -240,14 +240,18 @@ export const DetailsScreen = ({
       return;
     }
 
-    iframeDocument.documentElement.style.overscrollBehavior = 'none';
-    iframeDocument.documentElement.style.overscrollBehaviorX = 'none';
-    iframeDocument.documentElement.style.overscrollBehaviorY = 'none';
-
-    if (iframeDocument.body) {
-      iframeDocument.body.style.overscrollBehavior = 'none';
-      iframeDocument.body.style.overscrollBehaviorX = 'none';
-      iframeDocument.body.style.overscrollBehaviorY = 'none';
+    const { documentElement, body } = iframeDocument;
+
+    if (documentElement) {
+      documentElement.style.overscrollBehavior = 'none';
+      documentElement.style.overscrollBehaviorX = 'none';
+      documentElement.style.overscrollBehaviorY = 'none';
+    }
+
+    if (body) {
+      body.style.overscrollBehavior = 'none';
+      body.style.overscrollBehaviorX = 'none';
+      body.style.overscrollBehaviorY = 'none';
     }
   }, []);
 
diff --git a/code/addons/review/src/screens/SummaryScreen.stories.tsx b/code/addons/review/src/screens/SummaryScreen.stories.tsx
index 5edbe27999b9..72ca0d95094b 100644
--- a/code/addons/review/src/screens/SummaryScreen.stories.tsx
+++ b/code/addons/review/src/screens/SummaryScreen.stories.tsx
@@ -212,8 +212,9 @@ export const Minimal = meta.story({
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
     await expect(await canvas.findByText('Button prop rename')).toBeInTheDocument();
-    await expect(await canvas.findByText(/Showing 2 agent-curated stories/i)).toBeInTheDocument();
-    await expect(await canvas.findByText('update/button-styles')).toBeInTheDocument();
+    await expect(
+      await canvas.findByText(/Showing 2 agent-curated stories for quick review/i)
+    ).toBeInTheDocument();
     await expect(await canvas.findByRole('tab', { name: 'Collections' })).toBeInTheDocument();
   },
 });

From 42403d160f3be167602feb7252b862c40892aa51 Mon Sep 17 00:00:00 2001
From: Gert Hengeveld <info@ghengeveld.nl>
Date: Tue, 2 Jun 2026 19:08:28 +0200
Subject: [PATCH 04/14] Add timeout and deterministic error handling to
 baseline proxy

The baseline preview proxies to a remote Chromatic origin that can be
slow or unreachable. Bound the wait with timeout/proxyTimeout and return
a deterministic 502 via on.error so a dead connection fails fast instead
of hanging the review UI's baseline iframe.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 code/addons/review/src/preset.ts | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/code/addons/review/src/preset.ts b/code/addons/review/src/preset.ts
index 82e6b6bd75c3..64223bbaa46d 100644
--- a/code/addons/review/src/preset.ts
+++ b/code/addons/review/src/preset.ts
@@ -79,8 +79,25 @@ export const experimental_devServer = (app: ServerApp) => {
   const proxyRequest = createProxyMiddleware({
     target: BASELINE_TARGET_ORIGIN,
     changeOrigin: true,
+    // The baseline origin is a remote Chromatic server that can be slow or
+    // unreachable. Bound the wait and respond deterministically so a dead
+    // connection fails fast instead of hanging the review UI's baseline iframe.
+    timeout: 30_000,
+    proxyTimeout: 30_000,
     pathRewrite: (path) =>
       path.startsWith(BASELINE_PROXY_PATH) ? path.slice(BASELINE_PROXY_PATH.length) || '/' : path,
+    on: {
+      error: (_error, _req, res) => {
+        // `res` is a net.Socket on WebSocket upgrades; only HTTP responses
+        // carry a status code.
+        if ('writeHead' in res) {
+          if (!res.headersSent) {
+            res.writeHead(502, { 'Content-Type': 'text/plain' });
+          }
+          res.end('Baseline preview is unavailable.');
+        }
+      },
+    },
   }) as unknown as Middleware;
 
   app.use(BASELINE_PROXY_PATH, proxyRequest);

From 69045c53d3b3d91ff1e03e9df6bbda057a91c651 Mon Sep 17 00:00:00 2001
From: Gert Hengeveld <info@ghengeveld.nl>
Date: Wed, 3 Jun 2026 09:18:20 +0200
Subject: [PATCH 05/14] Fix Details story to assert on rendered preview, drop
 dead branchName prop

The Details play function asserted on "Latest on <branch>" text, a branch
footer that was removed when branch-specific copy was dropped from the
review UI. Assert on the always-rendered latest preview iframe instead,
matching DetailsScreen.stories, and remove the now-unused branchName prop
that was threaded into DetailsScreen but never rendered.
---
 code/addons/review/src/ReviewPage.stories.tsx    | 4 +++-
 code/addons/review/src/ReviewPage.ts             | 1 -
 code/addons/review/src/screens/DetailsScreen.tsx | 1 -
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/code/addons/review/src/ReviewPage.stories.tsx b/code/addons/review/src/ReviewPage.stories.tsx
index b705659612af..622400ea0e30 100644
--- a/code/addons/review/src/ReviewPage.stories.tsx
+++ b/code/addons/review/src/ReviewPage.stories.tsx
@@ -145,6 +145,8 @@ export const Details = meta.story({
     applyReviewState();
 
     await expect(await canvas.findByRole('button', { name: '2/3' })).toBeInTheDocument();
-    await expect(await canvas.findByText('Latest on feat/review-page')).toBeInTheDocument();
+    await expect(
+      await canvas.findByTitle('Latest manager-settings-guidepage--default')
+    ).toBeInTheDocument();
   },
 });
diff --git a/code/addons/review/src/ReviewPage.ts b/code/addons/review/src/ReviewPage.ts
index 3463eda0ee63..fb6ff1cb46b7 100644
--- a/code/addons/review/src/ReviewPage.ts
+++ b/code/addons/review/src/ReviewPage.ts
@@ -217,7 +217,6 @@ const ReviewPageContent: FC<{ search: string }> = ({ search }) => {
               },
           activeTab
         ),
-        branchName: state.branchName,
       });
     }
   }
diff --git a/code/addons/review/src/screens/DetailsScreen.tsx b/code/addons/review/src/screens/DetailsScreen.tsx
index 6f40d97c95ca..ba8bf8fff428 100644
--- a/code/addons/review/src/screens/DetailsScreen.tsx
+++ b/code/addons/review/src/screens/DetailsScreen.tsx
@@ -175,7 +175,6 @@ export interface DetailsScreenProps {
   nextHref: string;
   componentTitle?: string;
   storyName?: string;
-  branchName?: string;
 }
 
 const renderDetailTitle = ({

From 0e154c1cc15ca4d13ebc6e1ecb6d6574c35e2ad6 Mon Sep 17 00:00:00 2001
From: Gert Hengeveld <info@ghengeveld.nl>
Date: Wed, 3 Jun 2026 12:47:12 +0200
Subject: [PATCH 06/14] Add "New" badge for stories absent from the baseline

Fetch the baseline Storybook's index.json (via the existing review proxy,
keyed on the review's createdAt) and flag stories that don't exist in the
baseline with a positive "New" badge in the DetailsScreen toolbar. No badge
shows when the baseline is unavailable or the story already exists.
---
 code/addons/review/src/ReviewPage.stories.tsx | 60 +++++++++++++++++++
 code/addons/review/src/ReviewPage.ts          | 42 +++++++++++++
 .../src/screens/DetailsScreen.stories.tsx     | 11 ++++
 .../review/src/screens/DetailsScreen.tsx      | 17 +++++-
 4 files changed, 129 insertions(+), 1 deletion(-)

diff --git a/code/addons/review/src/ReviewPage.stories.tsx b/code/addons/review/src/ReviewPage.stories.tsx
index 622400ea0e30..cd29cd1bc802 100644
--- a/code/addons/review/src/ReviewPage.stories.tsx
+++ b/code/addons/review/src/ReviewPage.stories.tsx
@@ -64,6 +64,8 @@ const reviewState: ReviewState = {
   title: 'Manager settings polish',
   description: 'Updated settings views and spacing.',
   branchName: 'feat/review-page',
+  // Drives the baseline-index fetch (keyed on createdAt) for "New" detection.
+  createdAt: 1_700_000_000_000,
   collections: [
     {
       title: 'Settings',
@@ -77,6 +79,39 @@ const reviewState: ReviewState = {
   ],
 };
 
+// Baseline index served via the dev-server proxy. Intentionally omits
+// `manager-settings-checklist--default` so it reads as a newly added story,
+// while guidepage/aboutscreen already exist in the baseline.
+const baselineIndex = {
+  v: 5,
+  entries: {
+    'manager-settings-guidepage--default': {
+      type: 'story',
+      id: 'manager-settings-guidepage--default',
+      title: 'Manager/Settings/Guide Page',
+      name: 'Default',
+    },
+    'manager-settings-aboutscreen--default': {
+      type: 'story',
+      id: 'manager-settings-aboutscreen--default',
+      title: 'Manager/Settings/About Screen',
+      name: 'Default',
+    },
+  },
+};
+
+const originalFetch = globalThis.fetch;
+const fetchMock = fn(async (input: RequestInfo | URL): Promise<Response> => {
+  const url = typeof input === 'string' ? input : input.toString();
+  if (url.includes('/__review-baseline/index.json')) {
+    return new Response(JSON.stringify(baselineIndex), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+  return new Response(null, { status: 404 });
+});
+
 const applyReviewState = () => {
   expect(onMock).toHaveBeenCalledWith(EVENTS.DISPLAY_REVIEW, expect.any(Function));
   emitMock(EVENTS.DISPLAY_REVIEW, reviewState);
@@ -105,7 +140,12 @@ const meta = preview.meta({
     offMock.mockReset();
     emitMock.mockReset();
     toggleNavMock.mockReset();
+    fetchMock.mockClear();
     sessionStorage.removeItem(RESTORE_NAV_SESSION_KEY);
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    return () => {
+      globalThis.fetch = originalFetch;
+    };
   },
 });
 
@@ -148,5 +188,25 @@ export const Details = meta.story({
     await expect(
       await canvas.findByTitle('Latest manager-settings-guidepage--default')
     ).toBeInTheDocument();
+    // guidepage exists in the baseline index, so it must not be flagged "New".
+    await expect(canvas.queryByText('New')).not.toBeInTheDocument();
+  },
+});
+
+export const DetailsNewStory = meta.story({
+  parameters: {
+    routerInitialEntries: ['/?path=/review/collections/0/manager-settings-checklist--default'],
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(emitMock).toHaveBeenCalledWith(EVENTS.REQUEST_REVIEW);
+
+    applyReviewState();
+
+    await expect(
+      await canvas.findByTitle('Latest manager-settings-checklist--default')
+    ).toBeInTheDocument();
+    // checklist is absent from the baseline index, so it is newly added.
+    await expect(await canvas.findByText('New')).toBeInTheDocument();
   },
 });
diff --git a/code/addons/review/src/ReviewPage.ts b/code/addons/review/src/ReviewPage.ts
index fb6ff1cb46b7..af464a38bbcf 100644
--- a/code/addons/review/src/ReviewPage.ts
+++ b/code/addons/review/src/ReviewPage.ts
@@ -27,8 +27,16 @@ export const ReviewPage: FC = () =>
       search: location.search ?? '',
     })) as unknown as ReactNode);
 
+// Served through the dev-server proxy declared in `preset.ts`, pointing at the
+// baseline Storybook. Used to detect stories that don't exist in the baseline.
+const BASELINE_INDEX_URL = '/__review-baseline/index.json';
+
 const ReviewPageContent: FC<{ search: string }> = ({ search }) => {
   const [state, setState] = useState<ReviewState | null>(null);
+  // Story IDs present in the baseline Storybook's index. `null` means the
+  // baseline is unresolved or unavailable (no fetch yet, network/proxy error,
+  // or an unparseable index) — in which case no "New" badge is shown.
+  const [baselineStoryIds, setBaselineStoryIds] = useState<Set<string> | null>(null);
 
   const api = useStorybookApi();
   const { index } = useStorybookState();
@@ -52,6 +60,36 @@ const ReviewPageContent: FC<{ search: string }> = ({ search }) => {
     emit(EVENTS.REQUEST_REVIEW);
   }, [emit]);
 
+  // Resolve which stories exist in the baseline so newly added stories can be
+  // flagged. Keyed on `createdAt`: a freshly pushed review re-fetches the
+  // baseline index. Any non-OK outcome leaves the set `null` (no badge).
+  const reviewCreatedAt = state?.createdAt;
+  useEffect(() => {
+    if (reviewCreatedAt === undefined) {
+      return undefined;
+    }
+    let cancelled = false;
+    setBaselineStoryIds(null);
+    fetch(BASELINE_INDEX_URL)
+      .then((response) => (response.ok ? response.json() : null))
+      .then((data: { entries?: Record<string, unknown>; stories?: Record<string, unknown> }) => {
+        if (cancelled || !data) {
+          return;
+        }
+        const entries = data.entries ?? data.stories;
+        if (!entries || typeof entries !== 'object') {
+          return;
+        }
+        setBaselineStoryIds(new Set(Object.keys(entries)));
+      })
+      .catch(() => {
+        // Baseline unavailable — leave `null` so no "New" badge is shown.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [reviewCreatedAt]);
+
   const activeTab = parseReviewChangesActiveTab(search);
   const detailLocation = parseReviewChangesDetailLocation(search);
 
@@ -183,6 +221,9 @@ const ReviewPageContent: FC<{ search: string }> = ({ search }) => {
       const nextStoryId = detailStoryIds[nextStoryIndex];
       const currentStoryId = detailStoryIds[currentStoryIndex];
       const currentStoryInfo = storyInfo[currentStoryId];
+      // Only flag as new once the baseline index has resolved and confirms the
+      // story is absent. While unresolved/unavailable (`null`) no badge shows.
+      const isNew = baselineStoryIds !== null && !baselineStoryIds.has(currentStoryId);
       detailScreen = React.createElement(DetailsScreen, {
         title: detailTitle,
         storyId: currentStoryId,
@@ -190,6 +231,7 @@ const ReviewPageContent: FC<{ search: string }> = ({ search }) => {
         totalStories,
         componentTitle: currentStoryInfo?.title,
         storyName: currentStoryInfo?.name,
+        isNew,
         backHref: buildReviewChangesSummaryHref(activeTab),
         previousHref: buildReviewChangesDetailHref(
           detailLocation.kind === 'collection'
diff --git a/code/addons/review/src/screens/DetailsScreen.stories.tsx b/code/addons/review/src/screens/DetailsScreen.stories.tsx
index 5a91609039b1..ca992961793b 100644
--- a/code/addons/review/src/screens/DetailsScreen.stories.tsx
+++ b/code/addons/review/src/screens/DetailsScreen.stories.tsx
@@ -43,6 +43,17 @@ export const Default = meta.story({
     await expect(
       await canvas.findByTitle('Latest manager-settings-guidepage--default')
     ).toBeInTheDocument();
+    await expect(canvas.queryByText('New')).not.toBeInTheDocument();
+  },
+});
+
+export const NewStory = meta.story({
+  args: {
+    isNew: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(await canvas.findByText('New')).toBeInTheDocument();
   },
 });
 
diff --git a/code/addons/review/src/screens/DetailsScreen.tsx b/code/addons/review/src/screens/DetailsScreen.tsx
index ba8bf8fff428..fe899257be45 100644
--- a/code/addons/review/src/screens/DetailsScreen.tsx
+++ b/code/addons/review/src/screens/DetailsScreen.tsx
@@ -1,6 +1,6 @@
 import React, { useCallback, useEffect, useRef, useState } from 'react';
 
-import { Button } from 'storybook/internal/components';
+import { Badge, Button } from 'storybook/internal/components';
 import { STORY_RENDERED } from 'storybook/internal/core-events';
 import { styled } from 'storybook/theming';
 
@@ -64,6 +64,13 @@ const DetailTitleRegular = styled.span({
   fontWeight: 400,
 });
 
+// Sibling of the (ellipsizing) title so the badge stays fully visible while a
+// long component/story name truncates instead of clipping the badge.
+const TitleBadge = styled.div({
+  flexShrink: 0,
+  display: 'inline-flex',
+});
+
 type PreviewMode = '1up' | '2up';
 type VisibleSide = 'baseline' | 'latest';
 
@@ -175,6 +182,8 @@ export interface DetailsScreenProps {
   nextHref: string;
   componentTitle?: string;
   storyName?: string;
+  /** Whether this story is newly added relative to the baseline Storybook. */
+  isNew?: boolean;
 }
 
 const renderDetailTitle = ({
@@ -215,6 +224,7 @@ export const DetailsScreen = ({
   nextHref,
   componentTitle,
   storyName,
+  isNew,
 }: DetailsScreenProps) => {
   const latestPreviewSrc = storyPreviewUrl(storyId);
   const [baselinePreviewSrc, setBaselinePreviewSrc] = useState(() =>
@@ -403,6 +413,11 @@ export const DetailsScreen = ({
             </a>
           </Button>
           <DetailTitle>{renderDetailTitle({ title, componentTitle, storyName })}</DetailTitle>
+          {isNew ? (
+            <TitleBadge>
+              <Badge status="positive">New</Badge>
+            </TitleBadge>
+          ) : null}
         </ToolbarSide>
 
         <ToolbarSide>

From b429288c635d40a7442598871d87b7e95eea6c7c Mon Sep 17 00:00:00 2001
From: Gert Hengeveld <info@ghengeveld.nl>
Date: Wed, 3 Jun 2026 13:24:50 +0200
Subject: [PATCH 07/14] Improve review detail screen baseline comparison UX

- Hide the baseline preview, side-by-side toggle and bottom comparison
  bar for newly added stories (no baseline to compare against).
- Render the baseline pane and comparison bar immediately since baseline
  existence is known up front, instead of waiting for the iframe onload.
- Default to the 2-up side-by-side layout and remember the user's
  1up/2up choice across detail/summary navigation via sessionStorage.
---
 code/addons/review/src/constants.ts           |  5 ++
 .../src/screens/DetailsScreen.stories.tsx     | 16 ++++
 .../review/src/screens/DetailsScreen.tsx      | 78 ++++++++++++-------
 3 files changed, 71 insertions(+), 28 deletions(-)

diff --git a/code/addons/review/src/constants.ts b/code/addons/review/src/constants.ts
index 77d75e0e7cb2..83ccfe040e6c 100644
--- a/code/addons/review/src/constants.ts
+++ b/code/addons/review/src/constants.ts
@@ -7,6 +7,11 @@ export const REVIEW_CHANGES_URL = '/review/';
 // full-reload navigations between review screens. Value: 'restore' | 'keep'.
 export const RESTORE_NAV_SESSION_KEY = `${ADDON_ID}/restore-nav`;
 
+// sessionStorage key remembering the detail screen's preview layout so it
+// persists as the user moves between the detail and summary screens (and
+// across the full-reload navigations between them). Value: '1up' | '2up'.
+export const PREVIEW_MODE_SESSION_KEY = `${ADDON_ID}/preview-mode`;
+
 // `@storybook/addon-mcp` display-review tool call emits this event with the raw agent payload.
 const PUSH_REVIEW = `${ADDON_ID}/push-review`;
 // Display agent review in the UI
diff --git a/code/addons/review/src/screens/DetailsScreen.stories.tsx b/code/addons/review/src/screens/DetailsScreen.stories.tsx
index ca992961793b..3b7a370048bf 100644
--- a/code/addons/review/src/screens/DetailsScreen.stories.tsx
+++ b/code/addons/review/src/screens/DetailsScreen.stories.tsx
@@ -44,6 +44,11 @@ export const Default = meta.story({
       await canvas.findByTitle('Latest manager-settings-guidepage--default')
     ).toBeInTheDocument();
     await expect(canvas.queryByText('New')).not.toBeInTheDocument();
+    // Baseline existence is known up front, so the comparison bar renders
+    // immediately — without waiting for the baseline iframe's load event.
+    await expect(
+      await canvas.findByRole('button', { name: 'Side-by-side preview mode' })
+    ).toBeInTheDocument();
   },
 });
 
@@ -54,6 +59,17 @@ export const NewStory = meta.story({
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
     await expect(await canvas.findByText('New')).toBeInTheDocument();
+    await expect(
+      await canvas.findByTitle('Latest manager-settings-guidepage--default')
+    ).toBeInTheDocument();
+    // A new story has no baseline to compare against: no baseline preview, no
+    // side-by-side toggle, no bottom comparison bar.
+    await expect(
+      canvas.queryByTitle('Baseline manager-settings-guidepage--default')
+    ).not.toBeInTheDocument();
+    await expect(
+      canvas.queryByRole('button', { name: 'Side-by-side preview mode' })
+    ).not.toBeInTheDocument();
   },
 });
 
diff --git a/code/addons/review/src/screens/DetailsScreen.tsx b/code/addons/review/src/screens/DetailsScreen.tsx
index fe899257be45..aba4431f48eb 100644
--- a/code/addons/review/src/screens/DetailsScreen.tsx
+++ b/code/addons/review/src/screens/DetailsScreen.tsx
@@ -12,6 +12,8 @@ import {
   TransferIcon,
 } from '@storybook/icons';
 
+import { PREVIEW_MODE_SESSION_KEY } from '../constants.ts';
+
 const Page = styled.div(({ theme }) => ({
   display: 'flex',
   flexDirection: 'column',
@@ -74,6 +76,20 @@ const TitleBadge = styled.div({
 type PreviewMode = '1up' | '2up';
 type VisibleSide = 'baseline' | 'latest';
 
+const DEFAULT_PREVIEW_MODE: PreviewMode = '2up';
+
+// Read the persisted preview layout, defaulting to side-by-side. sessionStorage
+// can throw (privacy modes, disabled storage), so failures fall back silently.
+const readPreviewMode = (): PreviewMode => {
+  try {
+    return sessionStorage.getItem(PREVIEW_MODE_SESSION_KEY) === '1up'
+      ? '1up'
+      : DEFAULT_PREVIEW_MODE;
+  } catch {
+    return DEFAULT_PREVIEW_MODE;
+  }
+};
+
 const PreviewFrameWrap = styled.div<{ $singleUp: boolean }>(({ $singleUp }) => ({
   flex: 1,
   minHeight: 0,
@@ -231,11 +247,16 @@ export const DetailsScreen = ({
     toBaselinePreviewUrl(latestPreviewSrc)
   );
   const baselinePreviewSrcRef = useRef(baselinePreviewSrc);
-  const [isBaselineReady, setIsBaselineReady] = useState(false);
-  const [previewMode, setPreviewMode] = useState<PreviewMode>('1up');
+  const [previewMode, setPreviewMode] = useState<PreviewMode>(readPreviewMode);
   const [visibleSide, setVisibleSide] = useState<VisibleSide>('latest');
-  const isSingleUp = previewMode === '1up';
-  const effectiveVisibleSide = isBaselineReady ? visibleSide : 'latest';
+  // A newly added story has no baseline counterpart, so there's nothing to
+  // compare against: render only the latest preview, full-width, and hide the
+  // baseline pane, the side-by-side controls, and the bottom comparison bar.
+  // Baseline existence is known up front (from the index lookup in ReviewPage),
+  // so the baseline pane and comparison bar render immediately — no need to
+  // wait for the baseline iframe's load event.
+  const showBaseline = !isNew;
+  const isSingleUp = previewMode === '1up' || !showBaseline;
 
   const baselineFrameRef = useRef<HTMLIFrameElement>(null);
   const latestFrameRef = useRef<HTMLIFrameElement>(null);
@@ -316,10 +337,19 @@ export const DetailsScreen = ({
   }, [baselinePreviewSrc]);
 
   useEffect(() => {
-    setIsBaselineReady(false);
     setBaselinePreviewSrc(toBaselinePreviewUrl(latestPreviewSrc));
   }, [latestPreviewSrc]);
 
+  // Persist the user's layout choice so it carries across navigation between
+  // the detail and summary screens.
+  useEffect(() => {
+    try {
+      sessionStorage.setItem(PREVIEW_MODE_SESSION_KEY, previewMode);
+    } catch {
+      // Storage unavailable — the in-memory state still drives this session.
+    }
+  }, [previewMode]);
+
   useEffect(() => {
     const baselineFrame = baselineFrameRef.current;
     const latestFrame = latestFrameRef.current;
@@ -373,7 +403,6 @@ export const DetailsScreen = ({
     };
 
     const handleBaselineFrameLoad = () => {
-      setIsBaselineReady(true);
       attachBaselineStoryRenderedListener();
       setupScrollSync();
     };
@@ -383,7 +412,6 @@ export const DetailsScreen = ({
       if (latestLocationHref) {
         const nextBaselineUrl = toBaselinePreviewUrl(latestLocationHref);
         if (baselinePreviewSrcRef.current !== nextBaselineUrl) {
-          setIsBaselineReady(false);
           setBaselinePreviewSrc(nextBaselineUrl);
         }
       }
@@ -438,34 +466,28 @@ export const DetailsScreen = ({
       </Toolbar>
 
       <PreviewFrameWrap $singleUp={isSingleUp}>
-        <PreviewPane
-          $singleUp={isSingleUp}
-          $active={!isSingleUp || effectiveVisibleSide === 'baseline'}
-        >
-          <PreviewFrame
-            ref={baselineFrameRef}
-            title={`Baseline ${storyId}`}
-            src={baselinePreviewSrc}
-          />
-        </PreviewPane>
-        {isSingleUp ? null : <PreviewDivider $singleUp={isSingleUp} />}
-        <PreviewPane
-          $singleUp={isSingleUp}
-          $active={!isSingleUp || effectiveVisibleSide === 'latest'}
-        >
+        {showBaseline ? (
+          <>
+            <PreviewPane $singleUp={isSingleUp} $active={!isSingleUp || visibleSide === 'baseline'}>
+              <PreviewFrame
+                ref={baselineFrameRef}
+                title={`Baseline ${storyId}`}
+                src={baselinePreviewSrc}
+              />
+            </PreviewPane>
+            {isSingleUp ? null : <PreviewDivider $singleUp={isSingleUp} />}
+          </>
+        ) : null}
+        <PreviewPane $singleUp={isSingleUp} $active={!isSingleUp || visibleSide === 'latest'}>
           <PreviewFrame ref={latestFrameRef} title={`Latest ${storyId}`} src={latestPreviewSrc} />
         </PreviewPane>
       </PreviewFrameWrap>
 
-      {isBaselineReady ? (
+      {showBaseline ? (
         <BottomToolbar>
           <BottomHalf>
             <BottomLabel>
-              {isSingleUp
-                ? effectiveVisibleSide === 'baseline'
-                  ? 'Baseline'
-                  : 'Latest'
-                : 'Baseline'}
+              {isSingleUp ? (visibleSide === 'baseline' ? 'Baseline' : 'Latest') : 'Baseline'}
             </BottomLabel>
           </BottomHalf>
           <BottomDivider $singleUp={isSingleUp} />

From 43ba86fb72ff1b257554125ab6e2d3d7d8624e7a Mon Sep 17 00:00:00 2001
From: Gert Hengeveld <info@ghengeveld.nl>
Date: Wed, 3 Jun 2026 13:50:34 +0200
Subject: [PATCH 08/14] Route review addon sessionStorage access through a
 guarded helper

Centralize all sessionStorage usage in a single session-store utility that
guards every access (privacy modes, disabled storage, sandboxed iframes can
throw), so persistence degrades gracefully and in-memory state still drives
the current session.
---
 code/addons/review/src/ReviewPage.stories.tsx |  3 ++-
 code/addons/review/src/ReviewPage.ts          |  9 ++++---
 code/addons/review/src/manager.tsx            |  5 ++--
 .../review/src/screens/DetailsScreen.tsx      | 21 ++++-----------
 code/addons/review/src/session-store.ts       | 27 +++++++++++++++++++
 5 files changed, 42 insertions(+), 23 deletions(-)
 create mode 100644 code/addons/review/src/session-store.ts

diff --git a/code/addons/review/src/ReviewPage.stories.tsx b/code/addons/review/src/ReviewPage.stories.tsx
index cd29cd1bc802..edbd556b4164 100644
--- a/code/addons/review/src/ReviewPage.stories.tsx
+++ b/code/addons/review/src/ReviewPage.stories.tsx
@@ -7,6 +7,7 @@ import preview from '../../../.storybook/preview.tsx';
 import { EVENTS, RESTORE_NAV_SESSION_KEY } from './constants.ts';
 import type { ReviewState } from './review-state.ts';
 import { ReviewPage } from './ReviewPage.ts';
+import { sessionStore } from './session-store.ts';
 
 type EventListener = (payload?: unknown) => void;
 
@@ -141,7 +142,7 @@ const meta = preview.meta({
     emitMock.mockReset();
     toggleNavMock.mockReset();
     fetchMock.mockClear();
-    sessionStorage.removeItem(RESTORE_NAV_SESSION_KEY);
+    sessionStore.remove(RESTORE_NAV_SESSION_KEY);
     globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
     return () => {
       globalThis.fetch = originalFetch;
diff --git a/code/addons/review/src/ReviewPage.ts b/code/addons/review/src/ReviewPage.ts
index af464a38bbcf..e5591a31eebf 100644
--- a/code/addons/review/src/ReviewPage.ts
+++ b/code/addons/review/src/ReviewPage.ts
@@ -15,6 +15,7 @@ import {
   type ReviewTab,
 } from './review-navigation.ts';
 import type { ReviewState } from './review-state.ts';
+import { sessionStore } from './session-store.ts';
 import { DetailsScreen } from './screens/DetailsScreen.tsx';
 import { SummaryScreen } from './screens/SummaryScreen.tsx';
 
@@ -113,16 +114,16 @@ const ReviewPageContent: FC<{ search: string }> = ({ search }) => {
   // router handles as an SPA transition). A user who keeps the sidebar
   // collapsed by choice ('keep') is left untouched.
   useEffect(() => {
-    if (sessionStorage.getItem(RESTORE_NAV_SESSION_KEY) === null) {
-      sessionStorage.setItem(RESTORE_NAV_SESSION_KEY, api.getIsNavShown() ? 'restore' : 'keep');
+    if (sessionStore.read(RESTORE_NAV_SESSION_KEY) === null) {
+      sessionStore.write(RESTORE_NAV_SESSION_KEY, api.getIsNavShown() ? 'restore' : 'keep');
     }
     api.toggleNav(false);
 
     return () => {
-      if (sessionStorage.getItem(RESTORE_NAV_SESSION_KEY) === 'restore') {
+      if (sessionStore.read(RESTORE_NAV_SESSION_KEY) === 'restore') {
         api.toggleNav(true);
       }
-      sessionStorage.removeItem(RESTORE_NAV_SESSION_KEY);
+      sessionStore.remove(RESTORE_NAV_SESSION_KEY);
     };
   }, [api]);
 
diff --git a/code/addons/review/src/manager.tsx b/code/addons/review/src/manager.tsx
index d34766d798ef..5128e4d13f56 100644
--- a/code/addons/review/src/manager.tsx
+++ b/code/addons/review/src/manager.tsx
@@ -11,6 +11,7 @@ import {
   EVENTS,
 } from './constants.ts';
 import { ReviewPage } from './ReviewPage.ts';
+import { sessionStore } from './session-store.ts';
 
 addons.register(ADDON_ID, (api) => {
   // Safety net: the review page hides the sidebar and has no in-app exit, so
@@ -19,11 +20,11 @@ addons.register(ADDON_ID, (api) => {
   // route, restore a sidebar we hid. SPA exits (browser back) are already
   // handled by ReviewPage's effect cleanup.
   const path = new URLSearchParams(window.location.search).get('path') ?? '';
-  const restoreNav = sessionStorage.getItem(RESTORE_NAV_SESSION_KEY);
+  const restoreNav = sessionStore.read(RESTORE_NAV_SESSION_KEY);
   if (!path.startsWith(REVIEW_CHANGES_URL) && restoreNav !== null) {
     // Clear both 'restore' and 'keep' so a stale marker can't block fresh
     // nav-state capture on the next review visit.
-    sessionStorage.removeItem(RESTORE_NAV_SESSION_KEY);
+    sessionStore.remove(RESTORE_NAV_SESSION_KEY);
     if (restoreNav === 'restore') {
       api.toggleNav(true);
     }
diff --git a/code/addons/review/src/screens/DetailsScreen.tsx b/code/addons/review/src/screens/DetailsScreen.tsx
index aba4431f48eb..b0bfecaa9220 100644
--- a/code/addons/review/src/screens/DetailsScreen.tsx
+++ b/code/addons/review/src/screens/DetailsScreen.tsx
@@ -13,6 +13,7 @@ import {
 } from '@storybook/icons';
 
 import { PREVIEW_MODE_SESSION_KEY } from '../constants.ts';
+import { sessionStore } from '../session-store.ts';
 
 const Page = styled.div(({ theme }) => ({
   display: 'flex',
@@ -78,17 +79,9 @@ type VisibleSide = 'baseline' | 'latest';
 
 const DEFAULT_PREVIEW_MODE: PreviewMode = '2up';
 
-// Read the persisted preview layout, defaulting to side-by-side. sessionStorage
-// can throw (privacy modes, disabled storage), so failures fall back silently.
-const readPreviewMode = (): PreviewMode => {
-  try {
-    return sessionStorage.getItem(PREVIEW_MODE_SESSION_KEY) === '1up'
-      ? '1up'
-      : DEFAULT_PREVIEW_MODE;
-  } catch {
-    return DEFAULT_PREVIEW_MODE;
-  }
-};
+// Read the persisted preview layout, defaulting to side-by-side.
+const readPreviewMode = (): PreviewMode =>
+  sessionStore.read(PREVIEW_MODE_SESSION_KEY) === '1up' ? '1up' : DEFAULT_PREVIEW_MODE;
 
 const PreviewFrameWrap = styled.div<{ $singleUp: boolean }>(({ $singleUp }) => ({
   flex: 1,
@@ -343,11 +336,7 @@ export const DetailsScreen = ({
   // Persist the user's layout choice so it carries across navigation between
   // the detail and summary screens.
   useEffect(() => {
-    try {
-      sessionStorage.setItem(PREVIEW_MODE_SESSION_KEY, previewMode);
-    } catch {
-      // Storage unavailable — the in-memory state still drives this session.
-    }
+    sessionStore.write(PREVIEW_MODE_SESSION_KEY, previewMode);
   }, [previewMode]);
 
   useEffect(() => {
diff --git a/code/addons/review/src/session-store.ts b/code/addons/review/src/session-store.ts
new file mode 100644
index 000000000000..f9a12233a587
--- /dev/null
+++ b/code/addons/review/src/session-store.ts
@@ -0,0 +1,27 @@
+// The single place the review addon touches `sessionStorage`. Centralizing it
+// here keeps persistence consistent and guards every access: `sessionStorage`
+// can throw (privacy modes, disabled storage, sandboxed iframes), so failures
+// degrade gracefully and in-memory state still drives the current session.
+export const sessionStore = {
+  read(key: string): string | null {
+    try {
+      return sessionStorage.getItem(key);
+    } catch {
+      return null;
+    }
+  },
+  write(key: string, value: string): void {
+    try {
+      sessionStorage.setItem(key, value);
+    } catch {
+      // Storage unavailable — ignore.
+    }
+  },
+  remove(key: string): void {
+    try {
+      sessionStorage.removeItem(key);
+    } catch {
+      // Storage unavailable — ignore.
+    }
+  },
+};

From 7a1c1855a7a11fd4cd6d9df802100544fff10931 Mon Sep 17 00:00:00 2001
From: Gert Hengeveld <info@ghengeveld.nl>
Date: Wed, 3 Jun 2026 13:51:48 +0200
Subject: [PATCH 09/14] Show "New" badge for change-detection-flagged stories

The detail screen now treats a story as new when the change-detection
mechanism flags it (status-value:new), in addition to the existing
baseline-absence check. This surfaces newly added stories even when a
baseline exists or is unavailable.
---
 code/addons/review/src/ReviewPage.stories.tsx | 40 ++++++++++++++++++-
 code/addons/review/src/ReviewPage.ts          | 35 ++++++++++++++--
 2 files changed, 70 insertions(+), 5 deletions(-)

diff --git a/code/addons/review/src/ReviewPage.stories.tsx b/code/addons/review/src/ReviewPage.stories.tsx
index edbd556b4164..8567948bc4ab 100644
--- a/code/addons/review/src/ReviewPage.stories.tsx
+++ b/code/addons/review/src/ReviewPage.stories.tsx
@@ -1,6 +1,11 @@
 import { expect, fn, userEvent, within } from 'storybook/test';
 
-import { ManagerContext, type API, type State } from 'storybook/manager-api';
+import {
+  ManagerContext,
+  type API,
+  type State,
+  internal_fullStatusStore,
+} from 'storybook/manager-api';
 import { MemoryRouter } from 'storybook/internal/router';
 
 import preview from '../../../.storybook/preview.tsx';
@@ -143,6 +148,9 @@ const meta = preview.meta({
     toggleNavMock.mockReset();
     fetchMock.mockClear();
     sessionStore.remove(RESTORE_NAV_SESSION_KEY);
+    // Reset change-detection statuses so a story marking one "new" doesn't leak
+    // into stories that assert the absence of the badge.
+    internal_fullStatusStore.unset();
     globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
     return () => {
       globalThis.fetch = originalFetch;
@@ -211,3 +219,33 @@ export const DetailsNewStory = meta.story({
     await expect(await canvas.findByText('New')).toBeInTheDocument();
   },
 });
+
+export const DetailsChangeDetectedNew = meta.story({
+  parameters: {
+    routerInitialEntries: ['/?path=/review/collections/0/manager-settings-guidepage--default'],
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // guidepage exists in the baseline index, so the baseline check alone would
+    // not flag it. Mark it new via the change-detection status store instead.
+    internal_fullStatusStore.set([
+      {
+        storyId: 'manager-settings-guidepage--default',
+        typeId: 'storybook/change-detection',
+        value: 'status-value:new',
+        title: 'Change Detection',
+        description: '',
+      },
+    ]);
+
+    await expect(emitMock).toHaveBeenCalledWith(EVENTS.REQUEST_REVIEW);
+
+    applyReviewState();
+
+    await expect(
+      await canvas.findByTitle('Latest manager-settings-guidepage--default')
+    ).toBeInTheDocument();
+    // Flagged "New" by change-detection despite existing in the baseline.
+    await expect(await canvas.findByText('New')).toBeInTheDocument();
+  },
+});
diff --git a/code/addons/review/src/ReviewPage.ts b/code/addons/review/src/ReviewPage.ts
index e5591a31eebf..28b1ac196f28 100644
--- a/code/addons/review/src/ReviewPage.ts
+++ b/code/addons/review/src/ReviewPage.ts
@@ -1,7 +1,13 @@
 import React, { type FC, type ReactNode, useEffect, useMemo, useRef, useState } from 'react';
 
-import { useChannel, useStorybookApi, useStorybookState } from 'storybook/manager-api';
+import {
+  experimental_useStatusStore,
+  useChannel,
+  useStorybookApi,
+  useStorybookState,
+} from 'storybook/manager-api';
 import { Location, type RenderData, useNavigate } from 'storybook/internal/router';
+import type { StatusesByStoryIdAndTypeId } from 'storybook/internal/types';
 
 import type { StoryInfo } from './components/CollectionGrid.tsx';
 import { EVENTS, RESTORE_NAV_SESSION_KEY, REVIEW_CHANGES_URL } from './constants.ts';
@@ -32,6 +38,9 @@ export const ReviewPage: FC = () =>
 // baseline Storybook. Used to detect stories that don't exist in the baseline.
 const BASELINE_INDEX_URL = '/__review-baseline/index.json';
 
+// Change-detection status value marking a story as newly added.
+const NEW_STATUS_VALUE = 'status-value:new';
+
 const ReviewPageContent: FC<{ search: string }> = ({ search }) => {
   const [state, setState] = useState<ReviewState | null>(null);
   // Story IDs present in the baseline Storybook's index. `null` means the
@@ -149,6 +158,20 @@ const ReviewPageContent: FC<{ search: string }> = ({ search }) => {
     return info;
   }, [index, state]);
 
+  // Stories the change-detection mechanism flagged as newly added. This is an
+  // independent "New" signal from the baseline-index check: a story can be new
+  // here even when a baseline exists (e.g. added on this branch).
+  const allStatuses = experimental_useStatusStore() as StatusesByStoryIdAndTypeId;
+  const changeDetectedNewStoryIds = useMemo(() => {
+    const ids = new Set<string>();
+    for (const [storyId, statusesByType] of Object.entries(allStatuses)) {
+      if (Object.values(statusesByType).some((status) => status.value === NEW_STATUS_VALUE)) {
+        ids.add(storyId);
+      }
+    }
+    return ids;
+  }, [allStatuses]);
+
   // SPA navigation: imperatively attach a click listener to the container so
   // left-clicks on in-page review links push history and swap the iframe URL
   // without a manager reload (no flash). Real hrefs are kept for accessibility
@@ -222,9 +245,13 @@ const ReviewPageContent: FC<{ search: string }> = ({ search }) => {
       const nextStoryId = detailStoryIds[nextStoryIndex];
       const currentStoryId = detailStoryIds[currentStoryIndex];
       const currentStoryInfo = storyInfo[currentStoryId];
-      // Only flag as new once the baseline index has resolved and confirms the
-      // story is absent. While unresolved/unavailable (`null`) no badge shows.
-      const isNew = baselineStoryIds !== null && !baselineStoryIds.has(currentStoryId);
+      // A story is "New" if change-detection flagged it (regardless of any
+      // baseline), or once the baseline index has resolved and confirms the
+      // story is absent. While the baseline is unresolved/unavailable (`null`)
+      // it contributes nothing — only the change-detection signal applies.
+      const isNew =
+        changeDetectedNewStoryIds.has(currentStoryId) ||
+        (baselineStoryIds !== null && !baselineStoryIds.has(currentStoryId));
       detailScreen = React.createElement(DetailsScreen, {
         title: detailTitle,
         storyId: currentStoryId,

From 959730b6e94ffe0d6fbc304131ac31ae4f84f0c3 Mon Sep 17 00:00:00 2001
From: Gert Hengeveld <info@ghengeveld.nl>
Date: Wed, 3 Jun 2026 14:38:01 +0200
Subject: [PATCH 10/14] Fix review addon story mocks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove unsupported branchName prop passed to DetailsScreen in the
  ReviewFlowDemo prototype story (DetailsScreen never consumed it).
- Anchor ReviewPage story createdAt to Date.now() so the "Created … ago"
  label renders as a small, stable value instead of computing minutes
  against a fixed past timestamp (caused a huge number in Chromatic).
---
 code/addons/review/src/ReviewPage.stories.tsx               | 4 +++-
 code/addons/review/src/prototype/ReviewFlowDemo.stories.tsx | 1 -
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/code/addons/review/src/ReviewPage.stories.tsx b/code/addons/review/src/ReviewPage.stories.tsx
index 8567948bc4ab..4c31aa09ddee 100644
--- a/code/addons/review/src/ReviewPage.stories.tsx
+++ b/code/addons/review/src/ReviewPage.stories.tsx
@@ -71,7 +71,9 @@ const reviewState: ReviewState = {
   description: 'Updated settings views and spacing.',
   branchName: 'feat/review-page',
   // Drives the baseline-index fetch (keyed on createdAt) for "New" detection.
-  createdAt: 1_700_000_000_000,
+  // Anchored to "now" so the "Created … ago" label stays small and stable
+  // instead of computing minutes against a fixed past timestamp.
+  createdAt: Date.now(),
   collections: [
     {
       title: 'Settings',
diff --git a/code/addons/review/src/prototype/ReviewFlowDemo.stories.tsx b/code/addons/review/src/prototype/ReviewFlowDemo.stories.tsx
index faf9ea40b091..971153506072 100644
--- a/code/addons/review/src/prototype/ReviewFlowDemo.stories.tsx
+++ b/code/addons/review/src/prototype/ReviewFlowDemo.stories.tsx
@@ -136,7 +136,6 @@ const ReviewFlowPrototype: FC<{
                 },
             activeTab
           )}
-          branchName={state.branchName}
         />
       );
     }

From 3d06003a9e162fdf4e076f19639c74dd1a4b64b1 Mon Sep 17 00:00:00 2001
From: Gert Hengeveld <info@ghengeveld.nl>
Date: Wed, 3 Jun 2026 14:54:24 +0200
Subject: [PATCH 11/14] Restore chevron as the accessible collapse/expand
 control

Revert the summary header to a non-semantic clickable row (a pointer
affordance only) and move the accessible toggle back to the chevron
<Button>, which carries the aria-label and now aria-expanded state for
assistive tech. This also restores the chevron's column alignment under
the toolbar's expand/collapse-all button without the manual margin hack.
---
 .../review/src/screens/SummaryScreen.tsx      | 71 ++++++++++---------
 1 file changed, 37 insertions(+), 34 deletions(-)

diff --git a/code/addons/review/src/screens/SummaryScreen.tsx b/code/addons/review/src/screens/SummaryScreen.tsx
index 83b61e1f5552..0d5031ad341c 100644
--- a/code/addons/review/src/screens/SummaryScreen.tsx
+++ b/code/addons/review/src/screens/SummaryScreen.tsx
@@ -192,16 +192,11 @@ const CollectionBlock = styled.section(({ theme }) => ({
   borderBottom: `1px solid ${theme.appBorderColor}`,
 }));
 
-const CollectionHead = styled.button(({ theme }) => ({
-  // Rendered as a real <button> so the whole header row toggles with the
-  // keyboard (Enter/Space) and is announced via aria-expanded.
-  appearance: 'none',
-  margin: 0,
-  padding: 0,
-  border: 0,
-  font: 'inherit',
-  textAlign: 'left',
-  color: 'inherit',
+// A plain clickable row, not a semantic control: making the whole header
+// toggle is just a convenience affordance for pointer users. The real
+// accessible control is the chevron <Button> inside, which carries the
+// aria-label and aria-expanded state for assistive technologies.
+const CollectionHead = styled.div(({ theme }) => ({
   display: 'flex',
   width: '100%',
   cursor: 'pointer',
@@ -211,10 +206,6 @@ const CollectionHead = styled.button(({ theme }) => ({
   background: theme.background.app,
   containerType: 'scroll-state',
   containerName: 'sticky-heading',
-  '&:focus-visible': {
-    outline: '0 none',
-    boxShadow: `inset 0 0 0 2px ${theme.barSelectedColor}`,
-  },
 }));
 
 const CollectionHeadInner = styled.div(({ theme }) => ({
@@ -377,22 +368,28 @@ const CollectionsTab: FC<{
             <Collapsible
               collapsed={!isExpanded}
               summary={() => (
-                <CollectionHead
-                  type="button"
-                  aria-expanded={isExpanded}
-                  aria-label={isExpanded ? 'Collapse cluster' : 'Expand cluster'}
-                  onClick={() => onToggleCollection(index)}
-                >
+                <CollectionHead onClick={() => onToggleCollection(index)}>
                   <CollectionHeadInner>
                     <CollectionHeadText data-collapsible-title>
                       <CollectionLabel>{collection.title}</CollectionLabel>
                     </CollectionHeadText>
                     <CollectionControls>
                       <CollectionCount>{storyIds.length}</CollectionCount>
-                      <ToggleChevronIcon
-                        aria-hidden
-                        style={{ transform: `rotate(${isExpanded ? -180 : 0}deg)` }}
-                      />
+                      <Button
+                        variant="ghost"
+                        size="small"
+                        padding="small"
+                        ariaLabel={isExpanded ? 'Collapse cluster' : 'Expand cluster'}
+                        aria-expanded={isExpanded}
+                        onClick={(event) => {
+                          event.stopPropagation();
+                          onToggleCollection(index);
+                        }}
+                      >
+                        <ToggleChevronIcon
+                          style={{ transform: `rotate(${isExpanded ? -180 : 0}deg)` }}
+                        />
+                      </Button>
                     </CollectionControls>
                   </CollectionHeadInner>
                 </CollectionHead>
@@ -481,22 +478,28 @@ const ComponentsTab: FC<{
             <Collapsible
               collapsed={!isExpanded}
               summary={() => (
-                <CollectionHead
-                  type="button"
-                  aria-expanded={isExpanded}
-                  aria-label={isExpanded ? 'Collapse component' : 'Expand component'}
-                  onClick={() => onToggleComponent(group.componentId)}
-                >
+                <CollectionHead onClick={() => onToggleComponent(group.componentId)}>
                   <CollectionHeadInner>
                     <CollectionHeadText data-collapsible-title>
                       {renderComponentTitle(name)}
                     </CollectionHeadText>
                     <CollectionControls>
                       <CollectionCount>{storyIds.length}</CollectionCount>
-                      <ToggleChevronIcon
-                        aria-hidden
-                        style={{ transform: `rotate(${isExpanded ? -180 : 0}deg)` }}
-                      />
+                      <Button
+                        variant="ghost"
+                        size="small"
+                        padding="small"
+                        ariaLabel={isExpanded ? 'Collapse component' : 'Expand component'}
+                        aria-expanded={isExpanded}
+                        onClick={(event) => {
+                          event.stopPropagation();
+                          onToggleComponent(group.componentId);
+                        }}
+                      >
+                        <ToggleChevronIcon
+                          style={{ transform: `rotate(${isExpanded ? -180 : 0}deg)` }}
+                        />
+                      </Button>
                     </CollectionControls>
                   </CollectionHeadInner>
                 </CollectionHead>

From 3dde2f82339bfd0447385a5c87fb5927455c3d38 Mon Sep 17 00:00:00 2001
From: Gert Hengeveld <info@ghengeveld.nl>
Date: Wed, 3 Jun 2026 15:04:38 +0200
Subject: [PATCH 12/14] Move focus to detail back button and make summary inert

When opening the detail screen, focus stayed on the now-hidden summary
because React 18 drops a boolean `inert` prop. Set the DOM property
imperatively so the mounted summary leaves the tab order and a11y tree,
and focus the back control when the detail screen mounts.
---
 code/addons/review/src/ReviewPage.stories.tsx | 26 ++++++++++++++++++-
 code/addons/review/src/ReviewPage.ts          | 14 +++++++++-
 .../review/src/screens/DetailsScreen.tsx      | 11 +++++++-
 3 files changed, 48 insertions(+), 3 deletions(-)

diff --git a/code/addons/review/src/ReviewPage.stories.tsx b/code/addons/review/src/ReviewPage.stories.tsx
index 4c31aa09ddee..b1f15b9dd310 100644
--- a/code/addons/review/src/ReviewPage.stories.tsx
+++ b/code/addons/review/src/ReviewPage.stories.tsx
@@ -1,4 +1,4 @@
-import { expect, fn, userEvent, within } from 'storybook/test';
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
 
 import {
   ManagerContext,
@@ -204,6 +204,30 @@ export const Details = meta.story({
   },
 });
 
+export const DetailsFocusesBackButton = meta.story({
+  parameters: {
+    routerInitialEntries: ['/?path=/review/collections/0/manager-settings-guidepage--default'],
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(emitMock).toHaveBeenCalledWith(EVENTS.REQUEST_REVIEW);
+
+    applyReviewState();
+
+    // Opening a detail moves focus to the back control.
+    const backButton = await canvas.findByRole('link', { name: 'Back to review' });
+    await waitFor(() => expect(backButton).toHaveFocus());
+
+    // The summary stays mounted behind the detail screen…
+    const summaryHeading = canvas.getByText('Manager settings polish');
+    expect(summaryHeading).toBeInTheDocument();
+    // …but is inert and hidden from assistive tech so focus can't reach it.
+    const inertWrapper = summaryHeading.closest('[inert]');
+    expect(inertWrapper).not.toBeNull();
+    expect(inertWrapper).toHaveAttribute('aria-hidden', 'true');
+  },
+});
+
 export const DetailsNewStory = meta.story({
   parameters: {
     routerInitialEntries: ['/?path=/review/collections/0/manager-settings-checklist--default'],
diff --git a/code/addons/review/src/ReviewPage.ts b/code/addons/review/src/ReviewPage.ts
index b3ae73c6ad21..f83b8c4d05e6 100644
--- a/code/addons/review/src/ReviewPage.ts
+++ b/code/addons/review/src/ReviewPage.ts
@@ -180,6 +180,7 @@ const ReviewPageContent: FC<{ search: string }> = ({ search }) => {
   // interactions` doesn't flag the delegation root — the div isn't itself
   // interactive, it's just catching bubbled clicks from real <a> elements.
   const containerRef = useRef<HTMLDivElement>(null);
+  const summaryWrapperRef = useRef<HTMLDivElement>(null);
   useEffect(() => {
     const container = containerRef.current;
     if (!container) {
@@ -296,6 +297,17 @@ const ReviewPageContent: FC<{ search: string }> = ({ search }) => {
 
   const hasDetailScreen = detailScreen !== null;
 
+  // While the detail screen is open the summary stays mounted behind it, but
+  // must drop out of the tab order and the accessibility tree so keyboard and
+  // screen-reader focus can't reach it. React 18 doesn't serialize a boolean
+  // `inert` prop to the DOM, so toggle the property imperatively.
+  useEffect(() => {
+    const node = summaryWrapperRef.current;
+    if (node) {
+      node.inert = hasDetailScreen;
+    }
+  }, [hasDetailScreen]);
+
   return React.createElement(
     'div',
     { ref: containerRef, style: { display: 'contents' } },
@@ -305,8 +317,8 @@ const ReviewPageContent: FC<{ search: string }> = ({ search }) => {
       React.createElement(
         'div',
         {
+          ref: summaryWrapperRef,
           'aria-hidden': hasDetailScreen || undefined,
-          inert: hasDetailScreen || undefined,
           style: hasDetailScreen ? { pointerEvents: 'none' } : undefined,
         },
         React.createElement(SummaryScreen, {
diff --git a/code/addons/review/src/screens/DetailsScreen.tsx b/code/addons/review/src/screens/DetailsScreen.tsx
index b0bfecaa9220..87e6b37f4026 100644
--- a/code/addons/review/src/screens/DetailsScreen.tsx
+++ b/code/addons/review/src/screens/DetailsScreen.tsx
@@ -251,8 +251,17 @@ export const DetailsScreen = ({
   const showBaseline = !isNew;
   const isSingleUp = previewMode === '1up' || !showBaseline;
 
+  const backButtonRef = useRef<HTMLAnchorElement>(null);
   const baselineFrameRef = useRef<HTMLIFrameElement>(null);
   const latestFrameRef = useRef<HTMLIFrameElement>(null);
+
+  // Entering the detail screen moves focus here so keyboard and screen-reader
+  // users land on the back control instead of being stranded on the now-inert
+  // summary. Runs once on mount: navigating between stories swaps the iframe
+  // src in place without remounting, so prev/next don't steal focus back.
+  useEffect(() => {
+    backButtonRef.current?.focus();
+  }, []);
   const cleanupScrollSyncRef = useRef<(() => void) | null>(null);
   const cleanupBaselineStoryRenderedRef = useRef<(() => void) | null>(null);
   const syncingTargetRef = useRef<VisibleSide | null>(null);
@@ -425,7 +434,7 @@ export const DetailsScreen = ({
       <Toolbar>
         <ToolbarSide>
           <Button variant="ghost" size="small" padding="small" ariaLabel="Back to review" asChild>
-            <a href={backHref}>
+            <a ref={backButtonRef} href={backHref}>
               <ChevronSmallLeftIcon />
             </a>
           </Button>

From 420e2023b6a3ae5d7792d1b39f2931e041e5b2cb Mon Sep 17 00:00:00 2001
From: Gert Hengeveld <info@ghengeveld.nl>
Date: Wed, 3 Jun 2026 15:46:59 +0200
Subject: [PATCH 13/14] Focus detail title heading on entry instead of back
 button

Focusing the heading orients screen-reader users by what they opened
rather than landing on an action; the heading is a programmatic focus
target (tabindex=-1) with no focus ring.
---
 code/addons/review/src/ReviewPage.stories.tsx | 10 +++++----
 .../review/src/screens/DetailsScreen.tsx      | 22 ++++++++++++-------
 2 files changed, 20 insertions(+), 12 deletions(-)

diff --git a/code/addons/review/src/ReviewPage.stories.tsx b/code/addons/review/src/ReviewPage.stories.tsx
index b1f15b9dd310..7242e6e0130e 100644
--- a/code/addons/review/src/ReviewPage.stories.tsx
+++ b/code/addons/review/src/ReviewPage.stories.tsx
@@ -204,7 +204,7 @@ export const Details = meta.story({
   },
 });
 
-export const DetailsFocusesBackButton = meta.story({
+export const DetailsFocusesTitle = meta.story({
   parameters: {
     routerInitialEntries: ['/?path=/review/collections/0/manager-settings-guidepage--default'],
   },
@@ -214,9 +214,11 @@ export const DetailsFocusesBackButton = meta.story({
 
     applyReviewState();
 
-    // Opening a detail moves focus to the back control.
-    const backButton = await canvas.findByRole('link', { name: 'Back to review' });
-    await waitFor(() => expect(backButton).toHaveFocus());
+    // Opening a detail moves focus to its heading so users are oriented by what
+    // they opened. The summary's h1 is inert/aria-hidden, so the detail h2 is
+    // the only heading the accessibility tree exposes.
+    const heading = await canvas.findByRole('heading', { level: 2 });
+    await waitFor(() => expect(heading).toHaveFocus());
 
     // The summary stays mounted behind the detail screen…
     const summaryHeading = canvas.getByText('Manager settings polish');
diff --git a/code/addons/review/src/screens/DetailsScreen.tsx b/code/addons/review/src/screens/DetailsScreen.tsx
index 87e6b37f4026..cb2975b30ca9 100644
--- a/code/addons/review/src/screens/DetailsScreen.tsx
+++ b/code/addons/review/src/screens/DetailsScreen.tsx
@@ -52,6 +52,9 @@ const DetailTitle = styled.h2({
   fontSize: 14,
   fontWeight: 700,
   lineHeight: '20px',
+  // Focused programmatically on entry to orient screen-reader users; it's not a
+  // tab stop, so don't paint a focus ring on this non-interactive heading.
+  outline: 'none',
 });
 
 const DetailTitleMuted = styled.span(({ theme }) => ({
@@ -251,16 +254,17 @@ export const DetailsScreen = ({
   const showBaseline = !isNew;
   const isSingleUp = previewMode === '1up' || !showBaseline;
 
-  const backButtonRef = useRef<HTMLAnchorElement>(null);
+  const titleRef = useRef<HTMLHeadingElement>(null);
   const baselineFrameRef = useRef<HTMLIFrameElement>(null);
   const latestFrameRef = useRef<HTMLIFrameElement>(null);
 
-  // Entering the detail screen moves focus here so keyboard and screen-reader
-  // users land on the back control instead of being stranded on the now-inert
-  // summary. Runs once on mount: navigating between stories swaps the iframe
-  // src in place without remounting, so prev/next don't steal focus back.
+  // Entering the detail screen moves focus to its heading so keyboard and
+  // screen-reader users are oriented by what they just opened instead of being
+  // stranded on the now-inert summary. Runs once on mount: navigating between
+  // stories swaps the iframe src in place without remounting, so prev/next
+  // don't steal focus back.
   useEffect(() => {
-    backButtonRef.current?.focus();
+    titleRef.current?.focus();
   }, []);
   const cleanupScrollSyncRef = useRef<(() => void) | null>(null);
   const cleanupBaselineStoryRenderedRef = useRef<(() => void) | null>(null);
@@ -434,11 +438,13 @@ export const DetailsScreen = ({
       <Toolbar>
         <ToolbarSide>
           <Button variant="ghost" size="small" padding="small" ariaLabel="Back to review" asChild>
-            <a ref={backButtonRef} href={backHref}>
+            <a href={backHref}>
               <ChevronSmallLeftIcon />
             </a>
           </Button>
-          <DetailTitle>{renderDetailTitle({ title, componentTitle, storyName })}</DetailTitle>
+          <DetailTitle ref={titleRef} tabIndex={-1}>
+            {renderDetailTitle({ title, componentTitle, storyName })}
+          </DetailTitle>
           {isNew ? (
             <TitleBadge>
               <Badge status="positive">New</Badge>

From 52e8d0a43d4f74afddfe485e820e656d1e87a8e0 Mon Sep 17 00:00:00 2001
From: Gert Hengeveld <info@ghengeveld.nl>
Date: Wed, 3 Jun 2026 15:48:55 +0200
Subject: [PATCH 14/14] Add focus ring to the review search field

The "Find stories" input had no visible focus indicator. Mirror the
sidebar search: the wrapper owns the focus ring while the input stays
outline-less.
---
 code/addons/review/src/screens/SummaryScreen.tsx | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/code/addons/review/src/screens/SummaryScreen.tsx b/code/addons/review/src/screens/SummaryScreen.tsx
index 0d5031ad341c..d1b91eabeb93 100644
--- a/code/addons/review/src/screens/SummaryScreen.tsx
+++ b/code/addons/review/src/screens/SummaryScreen.tsx
@@ -151,6 +151,13 @@ const SearchField = styled.div(({ theme }) => ({
   boxShadow: `${theme.button.border} 0 0 0 1px inset`,
   padding: 2,
   paddingLeft: 6,
+  // Mirror the sidebar search field: the wrapper owns the focus ring while the
+  // inner input stays outline-less, so the whole field reads as focused.
+  '&:has(input:focus), &:has(input:active)': {
+    background: theme.background.app,
+    outline: `2px solid ${theme.color.secondary}`,
+    outlineOffset: 2,
+  },
 }));
 
 const SearchInput = styled.input(({ theme }) => ({