From b6cd203782fca11193f3f81b44133c039ec30237 Mon Sep 17 00:00:00 2001
From: Matt Alonso <malonso@cloudflare.com>
Date: Tue, 21 Jul 2026 17:22:48 -0500
Subject: [PATCH 1/2] Unify pull request source overview layout

Render the pull request description, status actions, and reviewer summary inside one consistent overview grid instead of separate nested cards. This keeps the existing data and behavior intact while making the source header reusable across the normal code view and shared review surfaces.
---
 core/App.css                                  |  31 ++++--
 core/SharedWalkthroughApp.tsx                 |  18 ++--
 core/app/components/ReviewCodeView.tsx        | 100 +++++++++++++-----
 .../walkthrough/WalkthroughDiffSurface.tsx    |   5 +
 4 files changed, 106 insertions(+), 48 deletions(-)

diff --git a/core/App.css b/core/App.css
index 5defcff5..a3fc0d5c 100644
--- a/core/App.css
+++ b/core/App.css
@@ -1756,23 +1756,28 @@ html[data-codiff-platform='darwin'] .sidebar {
   padding: 0 8px 8px 50px;
 }
 
-.codiff-source-description-footer-row {
-  align-items: stretch;
+.codiff-source-description-overview {
+  align-items: start;
   display: grid;
-  gap: 8px;
-  grid-template-columns: minmax(0, 1fr) minmax(260px, 320px);
+  gap: 12px;
+  grid-template-columns: minmax(0, 1fr) minmax(340px, 380px);
+  min-width: 0;
+}
+
+.codiff-source-description-overview-main,
+.codiff-source-description-overview-aside {
+  min-width: 0;
 }
 
-.codiff-source-description-footer-main,
-.codiff-source-description-footer-aside {
+.codiff-source-description-overview-aside {
   display: flex;
   flex-direction: column;
-  min-width: 0;
+  gap: 8px;
+  padding: 8px 8px 8px 0;
 }
 
-.codiff-source-description-footer-main > *,
-.codiff-source-description-footer-aside > * {
-  flex: 1;
+.codiff-source-description-overview-aside > * {
+  min-width: 0;
 }
 
 .source-description-comment-anonymous + .codiff-source-description-footer {
@@ -1982,10 +1987,14 @@ html[data-codiff-platform='darwin'] .sidebar {
 }
 
 @media (max-width: 1024px) {
-  .codiff-source-description-footer-row {
+  .codiff-source-description-overview {
     grid-template-columns: minmax(0, 1fr);
   }
 
+  .codiff-source-description-overview-aside {
+    padding: 0 8px 8px;
+  }
+
   .pull-request-merge-controls,
   .pull-request-merge-actions {
     justify-content: flex-start;
diff --git a/core/SharedWalkthroughApp.tsx b/core/SharedWalkthroughApp.tsx
index c075084e..d2a0a018 100644
--- a/core/SharedWalkthroughApp.tsx
+++ b/core/SharedWalkthroughApp.tsx
@@ -840,20 +840,12 @@ export function ReviewSurface({
         onMergePullRequest={mergePullRequest}
       />
     ) : undefined;
-  const sourceDescriptionFooter =
-    sourceDescriptionFooterMain && sourceDescriptionFooterAside ? (
-      <div className="codiff-source-description-footer-row">
-        <div className="codiff-source-description-footer-main">{sourceDescriptionFooterMain}</div>
-        <div className="codiff-source-description-footer-aside">{sourceDescriptionFooterAside}</div>
-      </div>
-    ) : (
-      (sourceDescriptionFooterMain ?? sourceDescriptionFooterAside)
-    );
   const sourceDescription =
     source.type === 'pull-request' ? (
       <PullRequestSourceDescription
         actions={sourceDescriptionActions}
-        footer={sourceDescriptionFooter}
+        footer={sourceDescriptionFooterMain}
+        footerAside={sourceDescriptionFooterAside}
         keymap={keymap}
         onUpdateDescription={interactive?.onUpdateDescription}
         onUpdateTitle={interactive?.onUpdateTitle}
@@ -875,7 +867,8 @@ export function ReviewSurface({
         reviewProps={commonReviewProps}
         scrollTarget={blockScrollTarget}
         sourceDescriptionActions={sourceDescriptionActions}
-        sourceDescriptionFooter={sourceDescriptionFooter}
+        sourceDescriptionFooter={sourceDescriptionFooterMain}
+        sourceDescriptionFooterAside={sourceDescriptionFooterAside}
       />
     );
   };
@@ -1158,7 +1151,8 @@ export function ReviewSurface({
               scrollTarget={treeScrollTarget}
               selectedPath={visibleSelectedPath}
               sourceDescriptionActions={sourceDescriptionActions}
-              sourceDescriptionFooter={sourceDescriptionFooter}
+              sourceDescriptionFooter={sourceDescriptionFooterMain}
+              sourceDescriptionFooterAside={sourceDescriptionFooterAside}
               walkthroughNotes={emptyWalkthroughNotes}
             />
           )
diff --git a/core/app/components/ReviewCodeView.tsx b/core/app/components/ReviewCodeView.tsx
index 14c53cfb..0bc31b41 100644
--- a/core/app/components/ReviewCodeView.tsx
+++ b/core/app/components/ReviewCodeView.tsx
@@ -943,6 +943,7 @@ function SourceDescriptionBody({
 export function PullRequestSourceDescription({
   actions,
   footer,
+  footerAside,
   keymap,
   onUpdateDescription,
   onUpdateTitle,
@@ -951,6 +952,7 @@ export function PullRequestSourceDescription({
 }: {
   actions?: ReactNode;
   footer?: ReactNode;
+  footerAside?: ReactNode;
   keymap?: CodiffKeymap;
   onUpdateDescription?: (body: string) => Promise<void> | void;
   onUpdateTitle?: (title: string) => Promise<void> | void;
@@ -972,6 +974,25 @@ export function PullRequestSourceDescription({
 
   const isCollapsed = (!sourceDescriptionHasBody && !canEditDescription) || collapsed;
   const layoutKey = `source-description-panel:${source.provider ?? ''}:${source.url}:${sourceTitle}:${sourceDescription}:${source.author?.login ?? ''}:${source.author?.avatarUrl ?? ''}:${isCollapsed ? 'collapsed' : 'open'}`;
+  const sourceDescriptionContent = (
+    <SourceDescriptionBody
+      author={sourceAuthor}
+      canEdit={canEditDescription}
+      description={sourceDescription}
+      keymap={keymap}
+      layoutKey={layoutKey}
+      onLayoutReady={() => {}}
+      onUpdateDescription={onUpdateDescription}
+      onUploadDescriptionAsset={onUploadDescriptionAsset}
+    />
+  );
+  const overviewAside =
+    footer || footerAside ? (
+      <aside className="codiff-source-description-overview-aside">
+        {footer}
+        {footerAside}
+      </aside>
+    ) : null;
 
   return (
     <div className="codiff-source-description-panel">
@@ -987,17 +1008,19 @@ export function PullRequestSourceDescription({
       />
       {!isCollapsed ? (
         <div className="codiff-source-description-panel-body">
-          <SourceDescriptionBody
-            author={sourceAuthor}
-            canEdit={canEditDescription}
-            description={sourceDescription}
-            keymap={keymap}
-            layoutKey={layoutKey}
-            onLayoutReady={() => {}}
-            onUpdateDescription={onUpdateDescription}
-            onUploadDescriptionAsset={onUploadDescriptionAsset}
-          />
-          {footer ? <div className="codiff-source-description-footer">{footer}</div> : null}
+          {overviewAside ? (
+            <div className="codiff-source-description-overview">
+              <div className="codiff-source-description-overview-main">
+                {sourceDescriptionContent}
+              </div>
+              {overviewAside}
+            </div>
+          ) : (
+            <>
+              {sourceDescriptionContent}
+              {footer ? <div className="codiff-source-description-footer">{footer}</div> : null}
+            </>
+          )}
         </div>
       ) : null}
     </div>
@@ -2486,6 +2509,7 @@ export function ReviewCodeView({
   source,
   sourceDescriptionActions,
   sourceDescriptionFooter,
+  sourceDescriptionFooterAside,
   supportsReviewCommentActions,
   theme = 'system',
   viewed,
@@ -2546,6 +2570,7 @@ export function ReviewCodeView({
   source: ReviewSource;
   sourceDescriptionActions?: ReactNode;
   sourceDescriptionFooter?: ReactNode;
+  sourceDescriptionFooterAside?: ReactNode;
   supportsReviewCommentActions: boolean;
   theme?: CodiffPreferences['theme'];
   viewed: Record<string, string>;
@@ -3802,20 +3827,44 @@ export function ReviewCodeView({
         {!sourceDescriptionCollapsed &&
         (sourceDescriptionHasContent || canEditSourceDescription) ? (
           <div className="codiff-source-description-panel-body">
-            <SourceDescriptionBody
-              ariaLabel={sourceDescriptionAriaLabel}
-              author={sourceAuthor}
-              canEdit={canEditSourceDescription}
-              description={sourceDescription}
-              keymap={keymap}
-              layoutKey="code-view-header"
-              onLayoutReady={noopLayoutReady}
-              onUpdateDescription={onUpdateSourceDescription}
-              onUploadDescriptionAsset={onUploadSourceDescriptionAsset}
-            />
-            {sourceDescriptionFooter ? (
-              <div className="codiff-source-description-footer">{sourceDescriptionFooter}</div>
-            ) : null}
+            {sourceDescriptionFooter || sourceDescriptionFooterAside ? (
+              <div className="codiff-source-description-overview">
+                <div className="codiff-source-description-overview-main">
+                  <SourceDescriptionBody
+                    ariaLabel={sourceDescriptionAriaLabel}
+                    author={sourceAuthor}
+                    canEdit={canEditSourceDescription}
+                    description={sourceDescription}
+                    keymap={keymap}
+                    layoutKey="code-view-header"
+                    onLayoutReady={noopLayoutReady}
+                    onUpdateDescription={onUpdateSourceDescription}
+                    onUploadDescriptionAsset={onUploadSourceDescriptionAsset}
+                  />
+                </div>
+                <aside className="codiff-source-description-overview-aside">
+                  {sourceDescriptionFooter}
+                  {sourceDescriptionFooterAside}
+                </aside>
+              </div>
+            ) : (
+              <>
+                <SourceDescriptionBody
+                  ariaLabel={sourceDescriptionAriaLabel}
+                  author={sourceAuthor}
+                  canEdit={canEditSourceDescription}
+                  description={sourceDescription}
+                  keymap={keymap}
+                  layoutKey="code-view-header"
+                  onLayoutReady={noopLayoutReady}
+                  onUpdateDescription={onUpdateSourceDescription}
+                  onUploadDescriptionAsset={onUploadSourceDescriptionAsset}
+                />
+                {sourceDescriptionFooter ? (
+                  <div className="codiff-source-description-footer">{sourceDescriptionFooter}</div>
+                ) : null}
+              </>
+            )}
           </div>
         ) : null}
       </div>
@@ -3833,6 +3882,7 @@ export function ReviewCodeView({
       sourceDescriptionAriaLabel,
       sourceDescriptionCollapsed,
       sourceDescriptionFooter,
+      sourceDescriptionFooterAside,
       sourceDescriptionHasContent,
       sourceDescriptionLabel,
       sourceTitle,
diff --git a/core/app/components/walkthrough/WalkthroughDiffSurface.tsx b/core/app/components/walkthrough/WalkthroughDiffSurface.tsx
index 29a7b32f..b0513709 100644
--- a/core/app/components/walkthrough/WalkthroughDiffSurface.tsx
+++ b/core/app/components/walkthrough/WalkthroughDiffSurface.tsx
@@ -35,6 +35,7 @@ export function WalkthroughDiffSurface({
   scrollTarget,
   sourceDescriptionActions,
   sourceDescriptionFooter,
+  sourceDescriptionFooterAside,
 }: {
   allowViewedToggle?: boolean;
   blocks: ReadonlyArray<ReviewDiffBlock>;
@@ -44,6 +45,7 @@ export function WalkthroughDiffSurface({
   scrollTarget: WalkthroughBlockScrollTarget | null;
   sourceDescriptionActions?: ReviewCodeViewProps['sourceDescriptionActions'];
   sourceDescriptionFooter?: ReviewCodeViewProps['sourceDescriptionFooter'];
+  sourceDescriptionFooterAside?: ReviewCodeViewProps['sourceDescriptionFooterAside'];
 }) {
   return (
     <div className="wt-stop wt-diff-surface">
@@ -62,6 +64,9 @@ export function WalkthroughDiffSurface({
         showSourceDescription
         sourceDescriptionActions={sourceDescriptionActions ?? reviewProps.sourceDescriptionActions}
         sourceDescriptionFooter={sourceDescriptionFooter ?? reviewProps.sourceDescriptionFooter}
+        sourceDescriptionFooterAside={
+          sourceDescriptionFooterAside ?? reviewProps.sourceDescriptionFooterAside
+        }
         walkthroughNotes={emptyWalkthroughNotes}
       />
     </div>

From 44778f2d3a3879435cfb8d3d5b7fbcb9c6e0b62a Mon Sep 17 00:00:00 2001
From: Matt Alonso <malonso@cloudflare.com>
Date: Tue, 21 Jul 2026 17:25:01 -0500
Subject: [PATCH 2/2] Keep the walkthrough arc fixed above local content

Render the walkthrough arc outside the flexing `.wt-hybrid` content container for every host, matching the existing Web presentation. This keeps chapter navigation visible while the diff body scrolls and removes the local-versus-Web placement distinction.
---
 .../walkthrough/NarrativeWalkthroughView.tsx  | 38 +++++++++++--------
 1 file changed, 22 insertions(+), 16 deletions(-)

diff --git a/core/app/components/walkthrough/NarrativeWalkthroughView.tsx b/core/app/components/walkthrough/NarrativeWalkthroughView.tsx
index aad330e5..ac072a37 100644
--- a/core/app/components/walkthrough/NarrativeWalkthroughView.tsx
+++ b/core/app/components/walkthrough/NarrativeWalkthroughView.tsx
@@ -663,21 +663,26 @@ export function NarrativeWalkthroughView({
         }
     : null;
 
+  const arc = (
+    <Arc
+      committable={committable}
+      navigation={navigation}
+      onShareWalkthrough={onShareWalkthrough}
+      shareWalkthroughDisabled={shareWalkthroughDisabled}
+      supportAvailable={supportAvailable}
+      walkthroughView={walkthroughView}
+    />
+  );
+
   return (
-    <div
-      className="wt-hybrid"
-      onPointerDownCapture={navigation.releaseStopScrollLock}
-      onTouchStartCapture={navigation.releaseStopScrollLock}
-      onWheelCapture={navigation.releaseStopScrollLock}
-    >
-      <Arc
-        committable={committable}
-        navigation={navigation}
-        onShareWalkthrough={onShareWalkthrough}
-        shareWalkthroughDisabled={shareWalkthroughDisabled}
-        supportAvailable={supportAvailable}
-        walkthroughView={walkthroughView}
-      />
+    <>
+      {arc}
+      <div
+        className="wt-hybrid"
+        onPointerDownCapture={navigation.releaseStopScrollLock}
+        onTouchStartCapture={navigation.releaseStopScrollLock}
+        onWheelCapture={navigation.releaseStopScrollLock}
+      >
 
       {navigation.mode === 'commit' ? (
         <CommitView
@@ -782,7 +787,8 @@ export function NarrativeWalkthroughView({
             <span className="wt-upnext-file">Chapter {navigation.index + 1}</span>
           </span>
         </button>
-      ) : null}
-    </div>
+        ) : null}
+      </div>
+    </>
   );
 }