From 27097ebdd67a35486f20fb9c26a2399a60025a43 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Sat, 5 Sep 2026 06:14:15 -0700
Subject: [PATCH] refactor(web): give composer layout one owner

---
 apps/web/src/components/ChatView.tsx          | 469 ++++++--------
 apps/web/src/components/chat/ChatComposer.tsx | 477 +-------------
 .../components/chat/ComposerFrame.test.tsx    | 373 +++++++++++
 .../web/src/components/chat/ComposerFrame.tsx | 588 ++++++++++++++++++
 4 files changed, 1165 insertions(+), 742 deletions(-)
 create mode 100644 apps/web/src/components/chat/ComposerFrame.test.tsx
 create mode 100644 apps/web/src/components/chat/ComposerFrame.tsx

diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index c0c79c93bec1..3f1e61140093 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -314,7 +314,7 @@ import { PullRequestThreadDialog } from "./PullRequestThreadDialog";
 import { MessagesTimeline } from "./chat/MessagesTimeline";
 import type { AssistantCitationRequest } from "./chat/AssistantCitationSource";
 import { resolveTimelineIsAtEnd } from "./chat/MessagesTimeline.logic";
-import { resolveComposerTimelineInset } from "./composerFooterLayout";
+import type { ComposerFrameLayout } from "./chat/ComposerFrame";
 import { ChatHeader } from "./chat/ChatHeader";
 import { PanelLayoutControls, RightPanelMaximizeControl } from "./chat/PanelLayoutControls";
 import { expandedImageKey, type ExpandedImagePreview } from "./chat/ExpandedImagePreview";
@@ -345,7 +345,6 @@ import {
   useLinkedThreadPullRequest,
 } from "./ThreadStatusIndicators";
 import type { ComposerBannerStackItem } from "./chat/ComposerBannerStack";
-import { ComposerSurface } from "./chat/ComposerSurface";
 import {
   hasAvailableCompactionProvider,
   hasDismissedResumeCompaction,
@@ -1652,16 +1651,13 @@ export default function ChatView(props: ChatViewProps) {
     () => legendListRef.current?.getScrollableNode() ?? null,
     [],
   );
-  const [composerOverlayElement, setComposerOverlayElement] = useState<HTMLDivElement | null>(null);
-  const [composerOverlayHeight, setComposerOverlayHeight] = useState(0);
-  const composerOverlayHeightRef = useRef(0);
-  // Space the timeline keeps clear above its end. Tracks the overlay while the
-  // composer is expanded and holds that height while it rests, so the resting
-  // composer never exposes rows that its expansion will cover.
-  const [composerTimelineInset, setComposerTimelineInset] = useState(0);
-  const composerTimelineInsetRef = useRef(0);
-  const composerRestingRef = useRef(false);
-  const [scrollToEndClearance, setScrollToEndClearance] = useState(0);
+  const [composerLayout, setComposerLayout] = useState<ComposerFrameLayout>({
+    mode: "expanded",
+    visibleHeight: 0,
+    reservedHeight: 0,
+  });
+  const { visibleHeight: composerOverlayHeight, reservedHeight: composerTimelineInset } =
+    composerLayout;
   const isAtEndRef = useRef(true);
   const isTimelineAtLogicalEnd = useCallback(() => isAtEndRef.current, []);
   // Whether the timeline's rows extend past the viewport above the composer.
@@ -4767,10 +4763,11 @@ export default function ChatView(props: ChatViewProps) {
       cancelTimelineLiveFollowForUserNavigation();
     }
   });
+  const readComposerVisibleHeight = useEffectEvent(() => composerOverlayHeight);
   useEffect(() => {
     const controller = createPageScrollController({
       getContainer: () => legendListRef.current?.getScrollableNode() ?? null,
-      getScrollPaddingBottomPx: () => composerOverlayElement?.getBoundingClientRect().height ?? 0,
+      getScrollPaddingBottomPx: readComposerVisibleHeight,
       onScrollStart: handlePageScrollStart,
     });
     pageScrollControllerRef.current = controller;
@@ -4781,7 +4778,7 @@ export default function ChatView(props: ChatViewProps) {
         pageScrollControllerRef.current = null;
       }
     };
-  }, [composerOverlayElement]);
+  }, []);
   const onComposerPageScrollKeyDown = useCallback((key: PageScrollKey) => {
     pageScrollControllerRef.current?.handleKeyDown(key);
   }, []);
@@ -5225,60 +5222,6 @@ export default function ChatView(props: ChatViewProps) {
       ? activePlan.steps
       : null;
 
-  const publishComposerOverlayHeight = useCallback((height: number) => {
-    const nextHeight = Math.ceil(height);
-    if (nextHeight <= 0) return;
-    const previousHeight = composerOverlayHeightRef.current;
-    if (previousHeight !== nextHeight) {
-      composerOverlayHeightRef.current = nextHeight;
-      setComposerOverlayHeight(nextHeight);
-    }
-    const nextInset = resolveComposerTimelineInset({
-      currentInset: composerTimelineInsetRef.current,
-      overlayHeight: nextHeight,
-      isResting: composerRestingRef.current,
-    });
-    if (composerTimelineInsetRef.current !== nextInset) {
-      composerTimelineInsetRef.current = nextInset;
-      setComposerTimelineInset(nextInset);
-    }
-    setScrollToEndClearance((currentClearance) =>
-      currentClearance === nextHeight ? currentClearance : nextHeight,
-    );
-  }, []);
-  // The composer reports its resting flag from a layout effect, which runs
-  // before this component's own layout effects and before any resize
-  // observation, so every measurement below sees the flag for its layout.
-  // Only the flag is stored here: the stored height still belongs to the
-  // previous layout, and the composer publishes the new layout's height
-  // itself once it has measured it.
-  const onComposerRestingChange = useCallback((resting: boolean) => {
-    composerRestingRef.current = resting;
-  }, []);
-  // A held reservation belongs to the previous thread's draft. Rebuild it from
-  // this thread's overlay so a tall draft elsewhere does not pad this one.
-  useLayoutEffect(() => {
-    if (!composerOverlayElement) return;
-    composerTimelineInsetRef.current = 0;
-    publishComposerOverlayHeight(composerOverlayElement.getBoundingClientRect().height);
-  }, [activeThreadKey, composerOverlayElement, publishComposerOverlayHeight]);
-
-  useLayoutEffect(() => {
-    if (!composerOverlayElement) return;
-
-    const updateHeight = () => {
-      publishComposerOverlayHeight(composerOverlayElement.getBoundingClientRect().height);
-    };
-
-    updateHeight();
-    if (typeof ResizeObserver === "undefined") return;
-
-    const resizeObserver = new ResizeObserver(updateHeight);
-    resizeObserver.observe(composerOverlayElement);
-    return () => {
-      resizeObserver.disconnect();
-    };
-  }, [composerOverlayElement, publishComposerOverlayHeight]);
   const activeThreadPr =
     replacementLinkedThreadPullRequest !== null
       ? (gitStatusQuery.data?.pr ?? null)
@@ -8141,7 +8084,7 @@ export default function ChatView(props: ChatViewProps) {
               {showScrollToBottom && (
                 <div
                   className="pointer-events-none absolute left-1/2 z-30 flex -translate-x-1/2 justify-center py-1.5"
-                  style={{ bottom: scrollToEndClearance + 4 }}
+                  style={{ bottom: composerOverlayHeight + 4 }}
                 >
                   <Button
                     aria-label="Scroll to end"
@@ -8161,224 +8104,190 @@ export default function ChatView(props: ChatViewProps) {
               )}
             </div>
 
-            {/* Input bar — centered hero while a draft has no messages, docked at the bottom otherwise */}
-            <div
-              ref={setComposerOverlayElement}
-              data-chat-composer-overlay="true"
-              className={
-                isDraftHeroState
-                  ? "pointer-events-none absolute inset-0 z-20 flex items-center"
-                  : "pointer-events-none absolute inset-x-0 bottom-0 z-20 pt-1.5 sm:pt-2"
+            {/* Input bar, centered for an empty draft and docked after sending. */}
+            <ChatComposer
+              composerRef={composerRef}
+              composerDraftTarget={composerDraftTarget}
+              environmentId={environmentId}
+              attachmentUploadsCapabilityKnown={attachmentUploadsCapabilityKnown}
+              supportsAttachmentUploads={supportsAttachmentUploads}
+              maxFileAttachmentBytes={maxFileAttachmentBytes}
+              routeKind={routeKind}
+              routeThreadRef={routeThreadRef}
+              draftId={draftId}
+              activeThreadId={activeThreadId}
+              activeThreadEnvironmentId={activeThread?.environmentId}
+              activeThread={activeThread}
+              promptHistoryMessages={timelineMessages}
+              isServerThread={isServerThread}
+              isLocalDraftThread={isLocalDraftThread}
+              forceExpandedOnMobile={forceExpandedMobileComposer && isDraftHeroState}
+              projectSelectionRequired={isLocalDraftThread && activeProject === null}
+              phase={phase}
+              isConnecting={isConnecting}
+              isSendBusy={isSendBusy}
+              sendDisabledReason={
+                feedbackUploading
+                  ? "Sending feedback"
+                  : threadDetailLoading
+                    ? "Messages loading"
+                    : null
               }
-            >
-              <div
-                ref={attachDraftHeroTransitionGroupRef}
-                className="w-full ps-[calc(env(safe-area-inset-left)+0.75rem)] pe-[calc(env(safe-area-inset-right)+0.75rem)] sm:ps-[calc(env(safe-area-inset-left)+1.25rem)] sm:pe-[calc(env(safe-area-inset-right)+1.25rem)]"
-              >
-                <div className="group/composer-stack pointer-events-auto relative z-10">
-                  {isDraftHeroState ? (
-                    <div className="absolute inset-x-0 bottom-full z-0">
-                      <div
-                        className="pb-8 group-has-data-[composer-shoulder-tab]/composer-stack:pb-4"
-                        style={
-                          forceExpandedMobileComposer
-                            ? {
-                                viewTransitionName: MOBILE_DRAFT_HEADLINE_VIEW_TRANSITION_NAME,
-                              }
-                            : undefined
-                        }
-                      >
-                        <DraftHeroHeadline
-                          draftId={draftId}
-                          activeProjectRef={activeProjectRef}
-                          activeProjectTitle={activeProject?.title ?? null}
-                        />
-                      </div>
-                    </div>
-                  ) : null}
-                  <div
-                    className="relative"
-                    style={
-                      forceExpandedMobileComposer
-                        ? { viewTransitionName: MOBILE_COMPOSER_VIEW_TRANSITION_NAME }
-                        : undefined
-                    }
-                  >
-                    <ComposerSurface.Shell contextStrip={showComposerContextStrip}>
-                      <ComposerSurface.Host>
-                        <div ref={attachDraftHeroComposerAnchorRef} className="relative z-10">
-                          <ChatComposer
-                            composerRef={composerRef}
-                            composerDraftTarget={composerDraftTarget}
-                            environmentId={environmentId}
-                            attachmentUploadsCapabilityKnown={attachmentUploadsCapabilityKnown}
-                            supportsAttachmentUploads={supportsAttachmentUploads}
-                            maxFileAttachmentBytes={maxFileAttachmentBytes}
-                            routeKind={routeKind}
-                            routeThreadRef={routeThreadRef}
-                            draftId={draftId}
-                            activeThreadId={activeThreadId}
-                            activeThreadEnvironmentId={activeThread?.environmentId}
-                            activeThread={activeThread}
-                            promptHistoryMessages={timelineMessages}
-                            isServerThread={isServerThread}
-                            isLocalDraftThread={isLocalDraftThread}
-                            forceExpandedOnMobile={forceExpandedMobileComposer && isDraftHeroState}
-                            projectSelectionRequired={isLocalDraftThread && activeProject === null}
-                            phase={phase}
-                            isConnecting={isConnecting}
-                            isSendBusy={isSendBusy}
-                            sendDisabledReason={
-                              feedbackUploading
-                                ? "Sending feedback"
-                                : threadDetailLoading
-                                  ? "Messages loading"
-                                  : null
+              isPreparingWorktree={isPreparingWorktree}
+              bannerItems={composerBannerItems}
+              // With attachments or contexts aboard the pick just inserts the
+              // text, so it sends as a prompt like the typed path would.
+              onUsageLimitsCommand={
+                usageLimitsOffered && usageLimitsKey !== null && !composerHasNonPromptContent
+                  ? openUsageLimits
+                  : undefined
+              }
+              environmentUnavailable={activeEnvironmentUnavailableState}
+              activePendingApproval={activePendingApproval}
+              pendingApprovals={pendingApprovals}
+              pendingUserInputs={pendingUserInputs}
+              activePendingProgress={activePendingProgress}
+              activePendingResolvedAnswers={activePendingResolvedAnswers}
+              activePendingIsResponding={activePendingIsResponding}
+              activePendingDraftAnswers={activePendingDraftAnswers}
+              activePendingQuestionIndex={activePendingQuestionIndex}
+              respondingRequestIds={respondingRequestIds}
+              showPlanFollowUpPrompt={showPlanFollowUpPrompt}
+              activeProposedPlan={activeProposedPlan}
+              activeTasksProgress={activeComposerTasksProgress}
+              activeTaskSteps={activeComposerTaskSteps}
+              threadSyncPhase={activeEnvironmentUnavailable ? null : threadSyncPhase}
+              runtimeMode={runtimeMode}
+              interactionMode={interactionMode}
+              lockedProvider={lockedProvider}
+              providerStatuses={providerStatuses as ServerProvider[]}
+              activeProjectDefaultModelSelection={activeProjectDefaultModelSelection}
+              activeThreadModelSelection={activeThread?.modelSelection}
+              activeContextWindow={activeContextWindow}
+              compactThreadUnavailable={compactThreadUnavailable}
+              compactDisabled={compactDisabled}
+              compactDisabledReason={compactDisabledReason}
+              resolvedTheme={resolvedTheme}
+              settings={settings}
+              keybindings={keybindings}
+              terminalOpen={Boolean(terminalUiState.terminalOpen)}
+              gitCwd={gitCwd}
+              restingControlsHost={restingComposerControlsHost}
+              restingControlsHaveLeadingContext={isGitRepo || showComposerEnvironmentIndicator}
+              onRestingControlsVisibilityChange={setRestingComposerControlsVisible}
+              getTimelineScrollableNode={getTimelineScrollableNode}
+              isTimelineAtLogicalEnd={isTimelineAtLogicalEnd}
+              timelineOverflows={timelineOverflows}
+              promptRef={promptRef}
+              composerImagesRef={composerImagesRef}
+              composerFilesRef={composerFilesRef}
+              composerTerminalContextsRef={composerTerminalContextsRef}
+              composerElementContextsRef={composerElementContextsRef}
+              onPageScrollKeyDown={onComposerPageScrollKeyDown}
+              onPageScrollKeyUp={onComposerPageScrollKeyUp}
+              onPageScrollRelease={onComposerPageScrollRelease}
+              onSend={onSend}
+              onInterrupt={onInterrupt}
+              onImplementPlanInNewThread={onImplementPlanInNewThread}
+              onRespondToApproval={onRespondToApproval}
+              onSelectActivePendingUserInputOption={onSelectActivePendingUserInputOption}
+              onAdvanceActivePendingUserInput={onAdvanceActivePendingUserInput}
+              onPreviousActivePendingUserInputQuestion={onPreviousActivePendingUserInputQuestion}
+              onChangeActivePendingUserInputCustomAnswer={
+                onChangeActivePendingUserInputCustomAnswer
+              }
+              onProviderModelSelect={onProviderModelSelect}
+              onOpenProviderSetup={openProviderSetup}
+              getModelDisabledReason={getModelDisabledReason}
+              toggleInteractionMode={toggleInteractionMode}
+              handleRuntimeModeChange={handleRuntimeModeChange}
+              handleInteractionModeChange={handleInteractionModeChange}
+              focusComposer={focusComposer}
+              scheduleComposerFocus={scheduleComposerFocus}
+              setThreadError={setThreadError}
+              onExpandImage={onExpandTimelineImage}
+              onFileOpen={openFileAttachment}
+              frame={{
+                layoutKey: activeThreadKey,
+                isDraftHeroState,
+                showContextStrip: showComposerContextStrip,
+                transitionGroupRef: attachDraftHeroTransitionGroupRef,
+                composerAnchorRef: attachDraftHeroComposerAnchorRef,
+                viewTransitionName: forceExpandedMobileComposer
+                  ? MOBILE_COMPOSER_VIEW_TRANSITION_NAME
+                  : undefined,
+                onLayoutChange: setComposerLayout,
+                headline: isDraftHeroState ? (
+                  <div className="absolute inset-x-0 bottom-full z-0">
+                    <div
+                      className="pb-8 group-has-data-[composer-shoulder-tab]/composer-stack:pb-4"
+                      style={
+                        forceExpandedMobileComposer
+                          ? {
+                              viewTransitionName: MOBILE_DRAFT_HEADLINE_VIEW_TRANSITION_NAME,
                             }
-                            isPreparingWorktree={isPreparingWorktree}
-                            bannerItems={composerBannerItems}
-                            // With attachments or contexts aboard the pick just inserts the
-                            // text, so it sends as a prompt like the typed path would.
-                            onUsageLimitsCommand={
-                              usageLimitsOffered &&
-                              usageLimitsKey !== null &&
-                              !composerHasNonPromptContent
-                                ? openUsageLimits
+                          : undefined
+                      }
+                    >
+                      <DraftHeroHeadline
+                        draftId={draftId}
+                        activeProjectRef={activeProjectRef}
+                        activeProjectTitle={activeProject?.title ?? null}
+                      />
+                    </div>
+                  </div>
+                ) : null,
+                contextStrip: (
+                  <div className="min-h-0">
+                    <div
+                      data-terminal-open={terminalUiState.terminalOpen ? "true" : undefined}
+                      className="relative z-0"
+                    >
+                      {mountComposerContextStrip && (
+                        <div className="pointer-events-auto">
+                          <BranchToolbar
+                            environmentId={activeThread.environmentId}
+                            threadId={activeThread.id}
+                            showGitControls={isGitRepo}
+                            {...(routeKind === "draft" && draftId ? { draftId } : {})}
+                            onEnvModeChange={onEnvModeChange}
+                            startFromOrigin={startFromOrigin}
+                            onStartFromOriginChange={onStartFromOriginChange}
+                            {...(canOverrideServerThreadEnvMode
+                              ? { effectiveEnvModeOverride: envMode }
+                              : {})}
+                            {...(canOverrideServerThreadEnvMode
+                              ? {
+                                  activeThreadBranchOverride: activeThreadBranch,
+                                  onActiveThreadBranchOverrideChange: setPendingServerThreadBranch,
+                                }
+                              : {})}
+                            envLocked={envLocked}
+                            onComposerFocusRequest={scheduleComposerFocus}
+                            {...(canCheckoutPullRequestIntoThread
+                              ? { onCheckoutPullRequestRequest: openPullRequestDialog }
+                              : {})}
+                            {...(hasMultipleEnvironments ? { onEnvironmentChange } : {})}
+                            autoEnvironmentLabel={autoEnvironmentLabel}
+                            onAutoEnvironment={
+                              draftId &&
+                              !envLocked &&
+                              hasMultipleEnvironments &&
+                              loadBalancingSettings.loadBalancingEnabled
+                                ? onAutoEnvironment
                                 : undefined
                             }
-                            environmentUnavailable={activeEnvironmentUnavailableState}
-                            activePendingApproval={activePendingApproval}
-                            pendingApprovals={pendingApprovals}
-                            pendingUserInputs={pendingUserInputs}
-                            activePendingProgress={activePendingProgress}
-                            activePendingResolvedAnswers={activePendingResolvedAnswers}
-                            activePendingIsResponding={activePendingIsResponding}
-                            activePendingDraftAnswers={activePendingDraftAnswers}
-                            activePendingQuestionIndex={activePendingQuestionIndex}
-                            respondingRequestIds={respondingRequestIds}
-                            showPlanFollowUpPrompt={showPlanFollowUpPrompt}
-                            activeProposedPlan={activeProposedPlan}
-                            activeTasksProgress={activeComposerTasksProgress}
-                            activeTaskSteps={activeComposerTaskSteps}
-                            threadSyncPhase={activeEnvironmentUnavailable ? null : threadSyncPhase}
-                            runtimeMode={runtimeMode}
-                            interactionMode={interactionMode}
-                            lockedProvider={lockedProvider}
-                            providerStatuses={providerStatuses as ServerProvider[]}
-                            activeProjectDefaultModelSelection={activeProjectDefaultModelSelection}
-                            activeThreadModelSelection={activeThread?.modelSelection}
-                            activeContextWindow={activeContextWindow}
-                            compactThreadUnavailable={compactThreadUnavailable}
-                            compactDisabled={compactDisabled}
-                            compactDisabledReason={compactDisabledReason}
-                            resolvedTheme={resolvedTheme}
-                            settings={settings}
-                            keybindings={keybindings}
-                            terminalOpen={Boolean(terminalUiState.terminalOpen)}
-                            gitCwd={gitCwd}
-                            restingControlsHost={restingComposerControlsHost}
-                            restingControlsHaveLeadingContext={
-                              isGitRepo || showComposerEnvironmentIndicator
-                            }
-                            onRestingControlsVisibilityChange={setRestingComposerControlsVisible}
-                            getTimelineScrollableNode={getTimelineScrollableNode}
-                            isTimelineAtLogicalEnd={isTimelineAtLogicalEnd}
-                            timelineOverflows={timelineOverflows}
-                            onComposerOverlayHeightChange={publishComposerOverlayHeight}
-                            onRestingChange={onComposerRestingChange}
-                            promptRef={promptRef}
-                            composerImagesRef={composerImagesRef}
-                            composerFilesRef={composerFilesRef}
-                            composerTerminalContextsRef={composerTerminalContextsRef}
-                            composerElementContextsRef={composerElementContextsRef}
-                            onPageScrollKeyDown={onComposerPageScrollKeyDown}
-                            onPageScrollKeyUp={onComposerPageScrollKeyUp}
-                            onPageScrollRelease={onComposerPageScrollRelease}
-                            onSend={onSend}
-                            onInterrupt={onInterrupt}
-                            onImplementPlanInNewThread={onImplementPlanInNewThread}
-                            onRespondToApproval={onRespondToApproval}
-                            onSelectActivePendingUserInputOption={
-                              onSelectActivePendingUserInputOption
-                            }
-                            onAdvanceActivePendingUserInput={onAdvanceActivePendingUserInput}
-                            onPreviousActivePendingUserInputQuestion={
-                              onPreviousActivePendingUserInputQuestion
-                            }
-                            onChangeActivePendingUserInputCustomAnswer={
-                              onChangeActivePendingUserInputCustomAnswer
-                            }
-                            onProviderModelSelect={onProviderModelSelect}
-                            onOpenProviderSetup={openProviderSetup}
-                            getModelDisabledReason={getModelDisabledReason}
-                            toggleInteractionMode={toggleInteractionMode}
-                            handleRuntimeModeChange={handleRuntimeModeChange}
-                            handleInteractionModeChange={handleInteractionModeChange}
-                            focusComposer={focusComposer}
-                            scheduleComposerFocus={scheduleComposerFocus}
-                            setThreadError={setThreadError}
-                            onExpandImage={onExpandTimelineImage}
-                            onFileOpen={openFileAttachment}
+                            availableEnvironments={logicalProjectEnvironments}
+                            composerControlsHostRef={setRestingComposerControlsHost}
+                            contextStripVisible={showComposerContextStrip}
                           />
                         </div>
-                      </ComposerSurface.Host>
-                      <div className="min-h-0">
-                        <div
-                          data-terminal-open={terminalUiState.terminalOpen ? "true" : undefined}
-                          className="relative z-0"
-                        >
-                          {mountComposerContextStrip && (
-                            <div className="pointer-events-auto">
-                              <BranchToolbar
-                                environmentId={activeThread.environmentId}
-                                threadId={activeThread.id}
-                                showGitControls={isGitRepo}
-                                {...(routeKind === "draft" && draftId ? { draftId } : {})}
-                                onEnvModeChange={onEnvModeChange}
-                                startFromOrigin={startFromOrigin}
-                                onStartFromOriginChange={onStartFromOriginChange}
-                                {...(canOverrideServerThreadEnvMode
-                                  ? { effectiveEnvModeOverride: envMode }
-                                  : {})}
-                                {...(canOverrideServerThreadEnvMode
-                                  ? {
-                                      activeThreadBranchOverride: activeThreadBranch,
-                                      onActiveThreadBranchOverrideChange:
-                                        setPendingServerThreadBranch,
-                                    }
-                                  : {})}
-                                envLocked={envLocked}
-                                onComposerFocusRequest={scheduleComposerFocus}
-                                {...(canCheckoutPullRequestIntoThread
-                                  ? { onCheckoutPullRequestRequest: openPullRequestDialog }
-                                  : {})}
-                                {...(hasMultipleEnvironments ? { onEnvironmentChange } : {})}
-                                autoEnvironmentLabel={autoEnvironmentLabel}
-                                onAutoEnvironment={
-                                  draftId &&
-                                  !envLocked &&
-                                  hasMultipleEnvironments &&
-                                  loadBalancingSettings.loadBalancingEnabled
-                                    ? onAutoEnvironment
-                                    : undefined
-                                }
-                                availableEnvironments={logicalProjectEnvironments}
-                                composerControlsHostRef={setRestingComposerControlsHost}
-                                contextStripVisible={showComposerContextStrip}
-                              />
-                            </div>
-                          )}
-                        </div>
-                      </div>
-                    </ComposerSurface.Shell>
-                    <div
-                      aria-hidden
-                      className="h-[calc(env(safe-area-inset-bottom)+1rem)] sm:h-[calc(env(safe-area-inset-bottom)+1.25rem)]"
-                    />
+                      )}
+                    </div>
                   </div>
-                </div>
-              </div>
-            </div>
+                ),
+              }}
+            />
 
             {activeThreadRef && activePreviewMiniPlayer && previewMiniPlayerVisible ? (
               <ThreadPreviewMiniPlayer
diff --git a/apps/web/src/components/chat/ChatComposer.tsx b/apps/web/src/components/chat/ChatComposer.tsx
index 0a54a2a55abb..cee5fee53ec5 100644
--- a/apps/web/src/components/chat/ChatComposer.tsx
+++ b/apps/web/src/components/chat/ChatComposer.tsx
@@ -102,6 +102,7 @@ import { ComposerActivityRow } from "./ComposerActivityStatus";
 import type { ThreadSyncPhase } from "../../threadSync";
 import { ComposerBanner } from "./ComposerBanner";
 import { ComposerSurface } from "./ComposerSurface";
+import { ComposerFrame, type ComposerFrameProps } from "./ComposerFrame";
 import {
   ComposerBannerStack,
   type ComposerBannerStackContent,
@@ -156,7 +157,6 @@ import {
   COMPOSER_FOOTER_WIDE_ACTIONS_COMPACT_BREAKPOINT_PX,
   getRestingComposerImagePreviewCounts,
   resolveRestingComposerControlsLayout,
-  shouldAnimateComposerRestingTransition,
   shouldUseCompactComposerPrimaryActions,
   shouldUseCompactComposerFooter,
   shouldUseRestingComposerLayout,
@@ -247,445 +247,6 @@ type ComposerCommandMenuPosition = {
 
 const COMPOSER_SCROLL_COLLAPSE_THRESHOLD_PX = 24;
 const COMPOSER_SCROLL_GESTURE_RESET_MS = 120;
-const COMPOSER_RESTING_TRANSITION_DURATION_MS = 280;
-const COMPOSER_RESTING_TRANSITION_CLEANUP_BUFFER_MS = 50;
-const COMPOSER_RESTING_TRANSITION_EASING = "cubic-bezier(0.32, 0.72, 0, 1)";
-const COMPOSER_RESTING_CONTROLS_ARRIVAL_DRIFT_PX = 4;
-
-function useComposerRestingTransition(
-  isCollapsed: boolean,
-  isResting: boolean,
-  restingControlsRef: React.RefObject<HTMLDivElement | null>,
-  onOverlayHeightChange: (height: number) => void,
-) {
-  const elementRef = useRef<HTMLDivElement>(null);
-  const isCollapsedRef = useRef(isCollapsed);
-  const previousCollapsedRef = useRef(isCollapsed);
-  const previousRestingRef = useRef(isResting);
-  const previousHeightRef = useRef<number | null>(null);
-  const previousContentOffsetsRef = useRef<{
-    promptFromTop: number | null;
-    promptHeight: number | null;
-    actionFromBottom: number | null;
-  }>({ promptFromTop: null, promptHeight: null, actionFromBottom: null });
-  const animationRef = useRef<Animation | null>(null);
-  const animationTargetHeightRef = useRef<number | null>(null);
-  const contentAnimationsRef = useRef<Animation[]>([]);
-  const stateChangeAnimationsRef = useRef<Animation[]>([]);
-  const pinnedOverlayRef = useRef<HTMLElement | null>(null);
-  const transitionCleanupTimeoutRef = useRef<number | null>(null);
-  const transitionLayoutRequestRef = useRef(0);
-  const hasCompletedInitialLayoutRef = useRef(false);
-
-  const clearOverlayPin = useCallback(() => {
-    // The overlay belongs to the chat view and outlives this composer, so it
-    // is remembered from pin time rather than re-resolved through a ref that
-    // React may already have detached during unmount.
-    const overlay = pinnedOverlayRef.current;
-    pinnedOverlayRef.current = null;
-    overlay?.style.removeProperty("height");
-    overlay?.style.removeProperty("display");
-    overlay?.style.removeProperty("flex-direction");
-    overlay?.style.removeProperty("justify-content");
-  }, []);
-
-  const clearTransitionStyles = useCallback(() => {
-    const element = elementRef.current;
-    const footer = element?.querySelector<HTMLElement>('[data-chat-composer-footer="true"]');
-    element?.style.removeProperty("overflow");
-    element
-      ?.querySelector<HTMLElement>('[data-chat-composer-surface="true"]')
-      ?.style.removeProperty("height");
-    footer?.style.removeProperty("position");
-    footer?.style.removeProperty("top");
-    footer?.style.removeProperty("bottom");
-    footer?.style.removeProperty("left");
-    footer?.style.removeProperty("right");
-    footer?.style.removeProperty("height");
-    clearOverlayPin();
-  }, [clearOverlayPin]);
-
-  isCollapsedRef.current = isCollapsed;
-
-  const transitionToCurrentGeometry = useCallback(
-    (stateChanged: boolean) => {
-      const element = elementRef.current;
-      const surface = element?.querySelector<HTMLElement>('[data-chat-composer-surface="true"]');
-      if (!element || !surface) return;
-
-      const nextIsCollapsed = isCollapsedRef.current;
-
-      const visibleTransitionElement = (selector: string) =>
-        Array.from(element.querySelectorAll<HTMLElement>(selector)).find(
-          (candidate) => candidate.getClientRects().length > 0,
-        ) ?? null;
-      const prompt = visibleTransitionElement(
-        '[data-testid="composer-editor"], [data-chat-composer-transition-prompt="true"]',
-      );
-      const action = visibleTransitionElement('[data-chat-composer-transition-actions="true"]');
-      const footer = element.querySelector<HTMLElement>('[data-chat-composer-footer="true"]');
-      const interruptedAnimation = animationRef.current;
-      const interruptedPromptTop = interruptedAnimation
-        ? (prompt?.getBoundingClientRect().top ?? null)
-        : null;
-      const interruptedActionTop = interruptedAnimation
-        ? (action?.getBoundingClientRect().top ?? null)
-        : null;
-      const interruptedHeight = interruptedAnimation
-        ? element.getBoundingClientRect().height
-        : null;
-      const interruptedTargetHeight = animationTargetHeightRef.current;
-      const interruptedCurrentTime =
-        typeof interruptedAnimation?.currentTime === "number"
-          ? interruptedAnimation.currentTime
-          : null;
-      const interruptedDuration = interruptedAnimation?.effect?.getComputedTiming().duration;
-      if (transitionCleanupTimeoutRef.current !== null) {
-        window.clearTimeout(transitionCleanupTimeoutRef.current);
-        transitionCleanupTimeoutRef.current = null;
-      }
-      interruptedAnimation?.cancel();
-      animationRef.current = null;
-      for (const animation of contentAnimationsRef.current) animation.cancel();
-      contentAnimationsRef.current = [];
-      // The reveal and fade animations keep their own schedule across the
-      // body-resize re-entries that retarget the geometry mid-flight (every
-      // transition with a draft triggers one); cancelling them there would
-      // pop their subjects to full visibility at the start of the tween.
-      if (stateChanged) {
-        for (const animation of stateChangeAnimationsRef.current) animation.cancel();
-        stateChangeAnimationsRef.current = [];
-      }
-      clearTransitionStyles();
-
-      const nextRect = element.getBoundingClientRect();
-      const nextHeight = nextRect.height;
-      // The chat view resize-observes the overlay to place the timeline
-      // inset, the scroll-to-end pill, and the mini player. Publishing the
-      // destination height here turns that feedback into one update instead
-      // of a ChatView re-render on every animation frame.
-      const overlay = element.closest<HTMLElement>('[data-chat-composer-overlay="true"]');
-      const overlayHeight = overlay?.getBoundingClientRect().height ?? null;
-      if (overlayHeight !== null) {
-        onOverlayHeightChange(overlayHeight);
-      }
-      const nextPromptRect = prompt?.getBoundingClientRect() ?? null;
-      const nextPromptTop = nextPromptRect?.top ?? null;
-      const nextActionTop = action?.getBoundingClientRect().top ?? null;
-      const previousHeight = interruptedHeight ?? previousHeightRef.current;
-      const targetChanged =
-        interruptedTargetHeight === null || Math.abs(interruptedTargetHeight - nextHeight) >= 0.5;
-      const prefersReducedMotion = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
-      const shouldAnimate = shouldAnimateComposerRestingTransition({
-        hasCompletedInitialLayout: hasCompletedInitialLayoutRef.current,
-        stateChanged,
-        hasInterruptedAnimation: interruptedHeight !== null,
-      });
-
-      if (
-        shouldAnimate &&
-        !prefersReducedMotion &&
-        previousHeight !== null &&
-        Math.abs(previousHeight - nextHeight) >= 0.5
-      ) {
-        const remainingDuration =
-          typeof interruptedDuration === "number" && interruptedCurrentTime !== null
-            ? Math.max(1, interruptedDuration - interruptedCurrentTime)
-            : COMPOSER_RESTING_TRANSITION_DURATION_MS;
-        const duration =
-          interruptedHeight !== null && !targetChanged
-            ? remainingDuration
-            : COMPOSER_RESTING_TRANSITION_DURATION_MS;
-        element.style.overflow = "clip";
-        surface.style.height = "100%";
-
-        // Pinning the overlay at the destination height keeps the resize
-        // observer quiet for the tween; bottom alignment keeps the animating
-        // surface glued to the overlay's stable bottom edge. The pin lasts
-        // only for the tween so later attachment, thread, font, and viewport
-        // changes remain natural.
-        if (overlay && overlayHeight !== null) {
-          overlay.style.height = `${String(overlayHeight)}px`;
-          overlay.style.display = "flex";
-          overlay.style.flexDirection = "column";
-          overlay.style.justifyContent = "flex-end";
-          pinnedOverlayRef.current = overlay;
-        }
-
-        // Keep the footer attached to the stable bottom edge while the outer
-        // height changes. Its resting absolute layout otherwise spans the old
-        // height on collapse, while its expanded flow layout falls below the
-        // clipped surface on expansion.
-        if (footer) {
-          footer.style.position = "absolute";
-          footer.style.top = "auto";
-          footer.style.bottom = "1px";
-          footer.style.height = "3rem";
-          if (nextIsCollapsed) {
-            footer.style.left = "auto";
-            footer.style.right = "1px";
-          } else {
-            footer.style.left = "1px";
-            footer.style.right = "1px";
-          }
-        }
-
-        const animation = element.animate(
-          [{ height: `${previousHeight}px` }, { height: `${nextHeight}px` }],
-          {
-            duration,
-            easing: COMPOSER_RESTING_TRANSITION_EASING,
-          },
-        );
-        animationRef.current = animation;
-        animationTargetHeightRef.current = nextHeight;
-
-        const animatedRect = element.getBoundingClientRect();
-        const previousPromptTop =
-          interruptedPromptTop ??
-          (previousContentOffsetsRef.current.promptFromTop === null
-            ? null
-            : animatedRect.top + previousContentOffsetsRef.current.promptFromTop);
-        const previousActionTop =
-          interruptedActionTop ??
-          (previousContentOffsetsRef.current.actionFromBottom === null
-            ? null
-            : animatedRect.bottom - previousContentOffsetsRef.current.actionFromBottom);
-        const contentAnimations: Animation[] = [];
-        const animateContentPosition = (
-          content: HTMLElement | null,
-          previousTop: number | null,
-        ) => {
-          if (!content || previousTop === null) return;
-          const offset = previousTop - content.getBoundingClientRect().top;
-          if (Math.abs(offset) < 0.5) return;
-          contentAnimations.push(
-            content.animate(
-              [{ transform: `translateY(${String(offset)}px)` }, { transform: "none" }],
-              {
-                duration,
-                easing: COMPOSER_RESTING_TRANSITION_EASING,
-              },
-            ),
-          );
-        };
-        animateContentPosition(prompt, previousPromptTop);
-        animateContentPosition(action, previousActionTop);
-        contentAnimationsRef.current = contentAnimations;
-
-        if (stateChanged) {
-          const stateChangeAnimations: Animation[] = [];
-
-          // A prompt that gains lines on expansion would otherwise slide up
-          // from under the footer band as one block. Opening a bottom clip in
-          // step with the tween instead unfurls the extra lines beneath the
-          // rising first line, so no text crosses the returning controls.
-          const previousPromptHeight = previousContentOffsetsRef.current.promptHeight;
-          if (
-            !nextIsCollapsed &&
-            prompt &&
-            nextPromptRect &&
-            previousPromptHeight !== null &&
-            nextPromptRect.height - previousPromptHeight >= 0.5
-          ) {
-            const hiddenHeight = nextPromptRect.height - previousPromptHeight;
-            stateChangeAnimations.push(
-              prompt.animate(
-                [
-                  { clipPath: `inset(0 0 ${String(hiddenHeight)}px 0)` },
-                  { clipPath: "inset(0 0 0 0)" },
-                ],
-                {
-                  duration,
-                  easing: COMPOSER_RESTING_TRANSITION_EASING,
-                },
-              ),
-            );
-          }
-
-          // The footer controls teleport between the composer footer and the
-          // context strip below it in a single commit. Fading the arriving
-          // cluster in along its direction of travel reads as one continuous
-          // move instead of a pop. Collapsing controls land in empty strip
-          // space and can appear immediately, but expanding controls return
-          // to the bottom row the prompt still occupies while the surface is
-          // short, so they stay hidden through the first half of the tween
-          // and fade in once the geometry has mostly settled.
-          const arrivingControls = nextIsCollapsed
-            ? restingControlsRef.current
-            : element.querySelector<HTMLElement>('[data-chat-composer-controls="left"]');
-          if (arrivingControls) {
-            const drift = nextIsCollapsed
-              ? -COMPOSER_RESTING_CONTROLS_ARRIVAL_DRIFT_PX
-              : COMPOSER_RESTING_CONTROLS_ARRIVAL_DRIFT_PX;
-            stateChangeAnimations.push(
-              arrivingControls.animate(
-                [
-                  { opacity: 0, transform: `translateY(${String(drift)}px)` },
-                  { opacity: 1, transform: "none" },
-                ],
-                {
-                  duration: nextIsCollapsed ? duration : duration / 2,
-                  delay: nextIsCollapsed ? 0 : duration / 2,
-                  fill: "backwards",
-                  easing: COMPOSER_RESTING_TRANSITION_EASING,
-                },
-              ),
-            );
-          }
-
-          const arrivingImagePreviews = nextIsCollapsed
-            ? Array.from(
-                element.querySelectorAll<HTMLElement>('[data-chat-composer-resting-images="true"]'),
-              )
-            : Array.from(
-                element.querySelectorAll<HTMLElement>('[data-chat-composer-expanded-image="true"]'),
-              );
-          for (const imagePreview of arrivingImagePreviews) {
-            stateChangeAnimations.push(
-              imagePreview.animate([{ opacity: 0 }, { opacity: 1 }], {
-                duration: nextIsCollapsed ? duration : duration / 2,
-                delay: nextIsCollapsed ? 0 : duration / 2,
-                fill: "backwards",
-                easing: COMPOSER_RESTING_TRANSITION_EASING,
-              }),
-            );
-          }
-          stateChangeAnimationsRef.current = stateChangeAnimations;
-        }
-
-        const finishTransition = (cancelAnimations: boolean) => {
-          if (animationRef.current !== animation) return;
-          if (transitionCleanupTimeoutRef.current !== null) {
-            window.clearTimeout(transitionCleanupTimeoutRef.current);
-            transitionCleanupTimeoutRef.current = null;
-          }
-          if (cancelAnimations) {
-            animation.cancel();
-            for (const contentAnimation of contentAnimationsRef.current) {
-              contentAnimation.cancel();
-            }
-            for (const stateChangeAnimation of stateChangeAnimationsRef.current) {
-              stateChangeAnimation.cancel();
-            }
-          }
-          animationRef.current = null;
-          animationTargetHeightRef.current = null;
-          contentAnimationsRef.current = [];
-          stateChangeAnimationsRef.current = [];
-          clearTransitionStyles();
-        };
-        void animation.finished.catch(() => undefined).then(() => finishTransition(false));
-        // A suspended document timeline can leave `finished` pending while
-        // these measurement styles remain active. Wall-clock cleanup makes
-        // the natural layout the eventual source of truth in that case.
-        transitionCleanupTimeoutRef.current = window.setTimeout(
-          () => finishTransition(true),
-          duration + COMPOSER_RESTING_TRANSITION_CLEANUP_BUFFER_MS,
-        );
-      } else {
-        animationTargetHeightRef.current = null;
-      }
-
-      previousCollapsedRef.current = nextIsCollapsed;
-      previousHeightRef.current = nextHeight;
-      previousContentOffsetsRef.current = {
-        promptFromTop: nextPromptTop === null ? null : nextPromptTop - nextRect.top,
-        promptHeight: nextPromptRect?.height ?? null,
-        actionFromBottom: nextActionTop === null ? null : nextRect.bottom - nextActionTop,
-      };
-    },
-    [clearTransitionStyles, onOverlayHeightChange, restingControlsRef],
-  );
-
-  useLayoutEffect(() => {
-    const requestId = transitionLayoutRequestRef.current + 1;
-    transitionLayoutRequestRef.current = requestId;
-    const stateChanged = previousCollapsedRef.current !== isCollapsed;
-    // A non-Git context strip enters or leaves flow through ChatView state in
-    // an earlier layout effect. Let React flush that parent update before the
-    // FLIP reads its destination geometry, while still running before paint.
-    queueMicrotask(() => {
-      if (transitionLayoutRequestRef.current !== requestId) return;
-      transitionToCurrentGeometry(stateChanged);
-    });
-    return () => {
-      if (transitionLayoutRequestRef.current === requestId) {
-        transitionLayoutRequestRef.current += 1;
-      }
-    };
-  }, [isCollapsed, transitionToCurrentGeometry]);
-
-  // The resting flag can change while the collapsed layout stays the same,
-  // for example when an unfocused thread crosses the phone breakpoint. The
-  // chat view pairs overlay heights with that flag, so republish the natural
-  // height for the new flag. A transition in flight publishes its own.
-  useLayoutEffect(() => {
-    if (previousRestingRef.current === isResting) return;
-    previousRestingRef.current = isResting;
-    if (animationRef.current) return;
-    const overlay = elementRef.current?.closest<HTMLElement>('[data-chat-composer-overlay="true"]');
-    if (overlay) onOverlayHeightChange(overlay.getBoundingClientRect().height);
-  }, [isResting, onOverlayHeightChange]);
-
-  useLayoutEffect(() => {
-    const element = elementRef.current;
-    if (!element || typeof ResizeObserver === "undefined") return;
-
-    const body = element.querySelector<HTMLElement>('[data-chat-composer-body="true"]');
-    const observer = new ResizeObserver((entries) => {
-      if (animationRef.current) {
-        if (body && entries.some((entry) => entry.target === body)) {
-          transitionToCurrentGeometry(false);
-        }
-        return;
-      }
-      const elementRect = element.getBoundingClientRect();
-      const visibleTransitionElement = (selector: string) =>
-        Array.from(element.querySelectorAll<HTMLElement>(selector)).find(
-          (candidate) => candidate.getClientRects().length > 0,
-        ) ?? null;
-      const promptRect = visibleTransitionElement(
-        '[data-testid="composer-editor"], [data-chat-composer-transition-prompt="true"]',
-      )?.getBoundingClientRect();
-      const actionTop = visibleTransitionElement(
-        '[data-chat-composer-transition-actions="true"]',
-      )?.getBoundingClientRect().top;
-      previousHeightRef.current = elementRect.height;
-      previousContentOffsetsRef.current = {
-        promptFromTop: promptRect === undefined ? null : promptRect.top - elementRect.top,
-        promptHeight: promptRect?.height ?? null,
-        actionFromBottom: actionTop === undefined ? null : elementRect.bottom - actionTop,
-      };
-    });
-    observer.observe(element);
-    if (body) observer.observe(body);
-    return () => observer.disconnect();
-  }, [transitionToCurrentGeometry]);
-
-  useEffect(() => {
-    // Host discovery and width measurement settle through layout updates on
-    // mount. Treat that bootstrap as initial geometry so an existing thread
-    // paints at rest instead of visibly collapsing from the expanded height.
-    hasCompletedInitialLayoutRef.current = true;
-    return () => {
-      if (transitionCleanupTimeoutRef.current !== null) {
-        window.clearTimeout(transitionCleanupTimeoutRef.current);
-        transitionCleanupTimeoutRef.current = null;
-      }
-      animationRef.current?.cancel();
-      animationRef.current = null;
-      animationTargetHeightRef.current = null;
-      for (const animation of contentAnimationsRef.current) animation.cancel();
-      contentAnimationsRef.current = [];
-      for (const animation of stateChangeAnimationsRef.current) animation.cancel();
-      stateChangeAnimationsRef.current = [];
-      clearTransitionStyles();
-    };
-  }, [clearTransitionStyles]);
-
-  return elementRef;
-}
 
 function composerCommandMenuPositionsEqual(
   a: ComposerCommandMenuPosition,
@@ -1256,12 +817,7 @@ export interface ChatComposerProps {
   isTimelineAtLogicalEnd: () => boolean;
   /** Whether the timeline has more content than fits above the composer. */
   timelineOverflows: boolean;
-  onComposerOverlayHeightChange: (height: number) => void;
-  /**
-   * Whether the desktop resting layout is active. Reported from a layout
-   * effect, so it is current before the chat view measures the overlay.
-   */
-  onRestingChange: (resting: boolean) => void;
+  frame: Omit<ComposerFrameProps, "children" | "mode" | "restingControlsRef">;
 
   // Refs the parent needs kept in sync
   promptRef: React.RefObject<string>;
@@ -1367,8 +923,6 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     getTimelineScrollableNode,
     isTimelineAtLogicalEnd,
     timelineOverflows,
-    onComposerOverlayHeightChange,
-    onRestingChange,
     promptRef,
     composerRef,
     composerImagesRef,
@@ -3733,9 +3287,6 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
   useLayoutEffect(() => {
     onRestingControlsVisibilityChange(composerControlsVisibleInStrip);
   }, [composerControlsVisibleInStrip, onRestingControlsVisibilityChange]);
-  useLayoutEffect(() => {
-    onRestingChange(isComposerResting);
-  }, [isComposerResting, onRestingChange]);
   const restingImagePreviewCounts = getRestingComposerImagePreviewCounts(
     standaloneComposerImages.length,
   );
@@ -3789,12 +3340,6 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
         ) : null}
       </div>
     ) : null;
-  const composerMainSurfaceRef = useComposerRestingTransition(
-    composerControlsInStrip,
-    isComposerResting,
-    restingComposerControlsRef,
-    onComposerOverlayHeightChange,
-  );
   const canTrackComposerScrollGesture =
     routeKind === "server" && activeThreadId !== null && !isMobileViewport;
   const canScrollCollapseComposer =
@@ -4772,7 +4317,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
 
   // Render
   // ------------------------------------------------------------------
-  return (
+  const composerForm = (
     <form
       ref={composerFormRef}
       onSubmit={submitComposer}
@@ -5020,10 +4565,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
         ) : null}
       </ComposerBanner.Dock>
       <div className="relative">
-        <ComposerSurface.Main
-          ref={composerMainSurfaceRef}
-          className={composerProviderState.composerFrameClassName}
-        >
+        <ComposerSurface.Main className={composerProviderState.composerFrameClassName}>
           <div
             ref={composerSurfaceRef}
             data-chat-composer-surface="true"
@@ -5666,4 +5208,15 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       </div>
     </form>
   );
+  return (
+    <ComposerFrame
+      {...props.frame}
+      mode={
+        isComposerResting ? "resting" : isComposerCollapsedMobile ? "mobile-collapsed" : "expanded"
+      }
+      restingControlsRef={restingComposerControlsRef}
+    >
+      {composerForm}
+    </ComposerFrame>
+  );
 });
diff --git a/apps/web/src/components/chat/ComposerFrame.test.tsx b/apps/web/src/components/chat/ComposerFrame.test.tsx
new file mode 100644
index 000000000000..0851690d401d
--- /dev/null
+++ b/apps/web/src/components/chat/ComposerFrame.test.tsx
@@ -0,0 +1,373 @@
+import { act, createRef, useCallback, useLayoutEffect, useState } from "react";
+import { create, type ReactTestRenderer } from "react-test-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import { ComposerFrame, type ComposerFrameLayout, type ComposerFrameMode } from "./ComposerFrame";
+import { timelineContentOverflowsViewport } from "./timelineScrollAnchoring";
+
+function createAnimation(duration: number, onStop: () => void) {
+  let finish: (() => void) | undefined;
+  const finished = new Promise<void>((resolve) => {
+    finish = resolve;
+  });
+  const stop = () => {
+    onStop();
+    finish?.();
+  };
+  return {
+    currentTime: 0,
+    effect: { getComputedTiming: () => ({ duration }) },
+    finished,
+    cancel: vi.fn(stop),
+    finish: stop,
+  };
+}
+
+// The fixture models natural height and the animation's temporary height.
+// Browser checks cover CSS geometry. These tests cover the frame's lifecycle.
+function createElementFixture(naturalHeight: number) {
+  const selectors = new Map<string, object>();
+  const animations: ReturnType<typeof createAnimation>[] = [];
+  const style = {
+    height: "",
+    removeProperty(property: string) {
+      const key = property.replace(/-([a-z])/g, (_: string, letter: string) =>
+        letter.toUpperCase(),
+      );
+      Reflect.set(style, key, "");
+      return "";
+    },
+  };
+  const element = {
+    naturalHeight,
+    animatedHeight: null as number | null,
+    style,
+    selectors,
+    animations,
+    getBoundingClientRect() {
+      const height = style.height
+        ? Number.parseFloat(style.height)
+        : (element.animatedHeight ?? element.naturalHeight);
+      return { top: 600 - height, bottom: 600, height };
+    },
+    querySelector: (selector: string) => selectors.get(selector) ?? null,
+    querySelectorAll: () => [],
+    animate: vi.fn((keyframes: Keyframe[], options: KeyframeAnimationOptions) => {
+      element.animatedHeight = Number.parseFloat(String(keyframes[0]?.height));
+      const animation = createAnimation(Number(options.duration), () => {
+        element.animatedHeight = null;
+      });
+      animations.push(animation);
+      return animation;
+    }),
+  };
+  return element;
+}
+
+class TestResizeObserver {
+  static active = new Set<TestResizeObserver>();
+  readonly targets = new Set<Element>();
+
+  constructor(readonly callback: ResizeObserverCallback) {
+    TestResizeObserver.active.add(this);
+  }
+
+  observe(target: Element) {
+    this.targets.add(target);
+  }
+
+  disconnect() {
+    TestResizeObserver.active.delete(this);
+  }
+
+  static resize(...elements: ReturnType<typeof createElementFixture>[]) {
+    for (const observer of TestResizeObserver.active) {
+      const entries = elements
+        .filter((element) => observer.targets.has(element as unknown as Element))
+        .map((target) => ({ target })) as unknown as ResizeObserverEntry[];
+      if (entries.length > 0) {
+        observer.callback(entries, observer as unknown as ResizeObserver);
+      }
+    }
+  }
+}
+
+interface FrameInput {
+  mode: ComposerFrameMode;
+  layoutKey: string;
+  height: number;
+  showContextStrip: boolean;
+  isDraftHeroState: boolean;
+}
+
+let renderer: ReactTestRenderer | null;
+let overlay: ReturnType<typeof createElementFixture>;
+let main: ReturnType<typeof createElementFixture>;
+let body: ReturnType<typeof createElementFixture>;
+let onLayoutChange: ReturnType<typeof vi.fn<(layout: ComposerFrameLayout) => void>>;
+let input: FrameInput;
+let reducedMotion: boolean;
+const restingControlsRef = createRef<HTMLDivElement>();
+
+function CommitGeometry({ height }: { height: number }) {
+  // Apply the fixture's DOM geometry before the frame's layout effect.
+  useLayoutEffect(() => {
+    overlay.naturalHeight = height;
+    main.naturalHeight = height - 60;
+  }, [height]);
+  return null;
+}
+
+function FrameCommit({
+  reportLayout = onLayoutChange,
+  ...props
+}: FrameInput & { reportLayout?: (layout: ComposerFrameLayout) => void }) {
+  return (
+    <>
+      <CommitGeometry height={props.height} />
+      <ComposerFrame
+        {...props}
+        headline={null}
+        contextStrip={null}
+        transitionGroupRef={null}
+        composerAnchorRef={null}
+        viewTransitionName={undefined}
+        restingControlsRef={restingControlsRef}
+        onLayoutChange={reportLayout}
+      >
+        <div data-chat-composer-main-surface="true" />
+      </ComposerFrame>
+    </>
+  );
+}
+
+async function renderFrame(update: Partial<FrameInput> = {}) {
+  input = { ...input, ...update };
+  await act(async () => {
+    if (renderer) {
+      renderer.update(<FrameCommit {...input} />);
+    } else {
+      renderer = create(<FrameCommit {...input} />, {
+        createNodeMock: () => overlay,
+      });
+    }
+  });
+}
+
+beforeEach(() => {
+  vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  vi.stubGlobal("ResizeObserver", TestResizeObserver);
+  reducedMotion = false;
+  vi.stubGlobal("window", {
+    setTimeout,
+    clearTimeout,
+    matchMedia: () => ({ matches: reducedMotion }),
+  });
+  overlay = createElementFixture(240);
+  main = createElementFixture(180);
+  body = createElementFixture(132);
+  overlay.selectors.set('[data-chat-composer-main-surface="true"]', main);
+  main.selectors.set('[data-chat-composer-surface="true"]', createElementFixture(180));
+  main.selectors.set('[data-chat-composer-body="true"]', body);
+  onLayoutChange = vi.fn();
+  renderer = null;
+  input = {
+    mode: "expanded",
+    layoutKey: "thread-a",
+    height: 240,
+    showContextStrip: false,
+    isDraftHeroState: false,
+  };
+});
+
+afterEach(async () => {
+  await act(() => renderer?.unmount());
+  expect(TestResizeObserver.active.size).toBe(0);
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
+describe("ComposerFrame", () => {
+  it("settles initial timeline overflow without animating a new thread", async () => {
+    function TimelineProbe({
+      composerInset,
+      onOverflowChange,
+    }: {
+      composerInset: number;
+      onOverflowChange: (overflows: boolean) => void;
+    }) {
+      useLayoutEffect(() => {
+        onOverflowChange(
+          timelineContentOverflowsViewport(
+            {
+              data: ["message"],
+              scroll: 0,
+              scrollLength: 800,
+              positionAtIndex: () => 0,
+              sizeAtIndex: () => 650,
+            },
+            { composerInset, anchorOffset: 24 },
+          ),
+        );
+      }, [composerInset, onOverflowChange]);
+      return null;
+    }
+
+    function OverflowFeedback() {
+      const [layout, setLayout] = useState<ComposerFrameLayout>({
+        mode: "expanded",
+        visibleHeight: 0,
+        reservedHeight: 0,
+      });
+      const [overflows, setOverflows] = useState(false);
+      const reportLayout = useCallback((next: ComposerFrameLayout) => {
+        onLayoutChange(next);
+        setLayout(next);
+      }, []);
+      const height = overflows ? 120 : 240;
+      return (
+        <>
+          <TimelineProbe composerInset={layout.reservedHeight} onOverflowChange={setOverflows} />
+          <FrameCommit
+            {...input}
+            mode={overflows ? "resting" : "expanded"}
+            height={height}
+            reportLayout={reportLayout}
+          />
+        </>
+      );
+    }
+
+    await act(async () => {
+      renderer = create(<OverflowFeedback />, { createNodeMock: () => overlay });
+    });
+    expect(onLayoutChange).toHaveBeenLastCalledWith({
+      mode: "resting",
+      visibleHeight: 120,
+      reservedHeight: 240,
+    });
+    expect(main.animate).not.toHaveBeenCalled();
+    expect(overlay.style.height).toBe("");
+  });
+
+  it("publishes mode and destination together without per-frame updates", async () => {
+    await renderFrame();
+    onLayoutChange.mockClear();
+
+    await renderFrame({ mode: "resting", height: 120, showContextStrip: true });
+    expect(onLayoutChange.mock.calls).toEqual([
+      [{ mode: "resting", visibleHeight: 120, reservedHeight: 240 }],
+    ]);
+    expect(overlay.style.height).toBe("120px");
+
+    main.animatedHeight = 140;
+    await act(() => TestResizeObserver.resize(main, overlay));
+    main.animatedHeight = 90;
+    await act(() => TestResizeObserver.resize(main, overlay));
+    expect(onLayoutChange).toHaveBeenCalledTimes(1);
+
+    await act(() => main.animations[0]?.finish());
+    expect(overlay.style.height).toBe("");
+    await act(() => TestResizeObserver.resize(overlay));
+    expect(onLayoutChange).toHaveBeenCalledTimes(1);
+
+    await renderFrame({ mode: "expanded", height: 240 });
+    expect(onLayoutChange).toHaveBeenLastCalledWith({
+      mode: "expanded",
+      visibleHeight: 240,
+      reservedHeight: 240,
+    });
+  });
+
+  it("drops the desktop reservation at the phone breakpoint even if height is unchanged", async () => {
+    await renderFrame({ mode: "resting", height: 120 });
+    expect(onLayoutChange).toHaveBeenLastCalledWith({
+      mode: "resting",
+      visibleHeight: 120,
+      reservedHeight: 214,
+    });
+
+    await renderFrame({ mode: "mobile-collapsed" });
+    expect(onLayoutChange).toHaveBeenLastCalledWith({
+      mode: "mobile-collapsed",
+      visibleHeight: 120,
+      reservedHeight: 120,
+    });
+    expect(main.animate).not.toHaveBeenCalled();
+  });
+
+  it("cancels the old thread's transition and starts a new reservation", async () => {
+    await renderFrame({ height: 450 });
+    await renderFrame({ mode: "resting", height: 120 });
+    const interrupted = main.animations[0];
+    expect(interrupted).toBeDefined();
+    onLayoutChange.mockClear();
+
+    await renderFrame({ layoutKey: "thread-b", height: 100 });
+    expect(interrupted?.cancel).toHaveBeenCalledOnce();
+    expect(overlay.style.height).toBe("");
+    expect(main.animations).toHaveLength(1);
+    expect(onLayoutChange.mock.calls).toEqual([
+      [{ mode: "resting", visibleHeight: 100, reservedHeight: 194 }],
+    ]);
+  });
+
+  it("retargets a changing body and context strip with one coherent reservation", async () => {
+    await renderFrame();
+    await renderFrame({ mode: "resting", height: 120 });
+    const first = main.animations[0];
+    onLayoutChange.mockClear();
+
+    overlay.naturalHeight = 260;
+    main.naturalHeight = 200;
+    await act(() => TestResizeObserver.resize(body));
+    expect(first?.cancel).toHaveBeenCalledOnce();
+    expect(onLayoutChange.mock.calls).toEqual([
+      [{ mode: "resting", visibleHeight: 260, reservedHeight: 354 }],
+    ]);
+    expect(overlay.style.height).toBe("260px");
+
+    await renderFrame({ height: 290, showContextStrip: true });
+    expect(onLayoutChange).toHaveBeenLastCalledWith({
+      mode: "resting",
+      visibleHeight: 290,
+      reservedHeight: 384,
+    });
+    expect(overlay.style.height).toBe("290px");
+  });
+
+  it("updates natural height without animation for reduced motion", async () => {
+    reducedMotion = true;
+    await renderFrame();
+    await renderFrame({ mode: "resting", height: 120 });
+    expect(main.animate).not.toHaveBeenCalled();
+    expect(overlay.style.height).toBe("");
+
+    await renderFrame({ mode: "expanded", height: 240 });
+    onLayoutChange.mockClear();
+    overlay.naturalHeight = 280.2;
+    await act(() => TestResizeObserver.resize(overlay));
+    overlay.naturalHeight = 280.4;
+    await act(() => TestResizeObserver.resize(overlay));
+    expect(onLayoutChange.mock.calls).toEqual([
+      [{ mode: "expanded", visibleHeight: 281, reservedHeight: 281 }],
+    ]);
+  });
+
+  it("releases a pin when the document timeline stops or the frame unmounts", async () => {
+    await renderFrame();
+    await renderFrame({ mode: "resting", height: 120 });
+    await act(() => vi.runAllTimers());
+    expect(overlay.style.height).toBe("");
+    expect(main.animations[0]?.cancel).toHaveBeenCalledOnce();
+
+    await renderFrame({ mode: "expanded", height: 240 });
+    expect(overlay.style.height).toBe("240px");
+    await act(() => renderer?.unmount());
+    renderer = null;
+    expect(overlay.style.height).toBe("");
+    expect(main.animations[1]?.cancel).toHaveBeenCalledOnce();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});
diff --git a/apps/web/src/components/chat/ComposerFrame.tsx b/apps/web/src/components/chat/ComposerFrame.tsx
new file mode 100644
index 000000000000..2fa1b18aa99a
--- /dev/null
+++ b/apps/web/src/components/chat/ComposerFrame.tsx
@@ -0,0 +1,588 @@
+import {
+  type ReactNode,
+  type Ref,
+  type RefObject,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+} from "react";
+
+import {
+  resolveComposerTimelineInset,
+  shouldAnimateComposerRestingTransition,
+} from "../composerFooterLayout";
+import { ComposerSurface } from "./ComposerSurface";
+
+export type ComposerFrameMode = "expanded" | "resting" | "mobile-collapsed";
+
+export interface ComposerFrameLayout {
+  mode: ComposerFrameMode;
+  /** Destination height, held steady while the composer animates. */
+  visibleHeight: number;
+  /** Space for the expanded composer, including while it rests. */
+  reservedHeight: number;
+}
+
+export interface ComposerFrameProps {
+  children: ReactNode;
+  mode: ComposerFrameMode;
+  layoutKey: string | null;
+  isDraftHeroState: boolean;
+  headline: ReactNode;
+  contextStrip: ReactNode;
+  showContextStrip: boolean;
+  transitionGroupRef: Ref<HTMLDivElement>;
+  composerAnchorRef: Ref<HTMLDivElement>;
+  viewTransitionName: string | undefined;
+  restingControlsRef: RefObject<HTMLDivElement | null>;
+  onLayoutChange: (layout: ComposerFrameLayout) => void;
+}
+
+const COMPOSER_RESTING_TRANSITION_DURATION_MS = 280;
+const COMPOSER_RESTING_TRANSITION_CLEANUP_BUFFER_MS = 50;
+const COMPOSER_RESTING_TRANSITION_EASING = "cubic-bezier(0.32, 0.72, 0, 1)";
+const COMPOSER_RESTING_CONTROLS_ARRIVAL_DRIFT_PX = 4;
+
+function useComposerFrameLayout({
+  mode,
+  layoutKey,
+  isDraftHeroState,
+  showContextStrip,
+  restingControlsRef,
+  onLayoutChange,
+}: Pick<
+  ComposerFrameProps,
+  | "mode"
+  | "layoutKey"
+  | "isDraftHeroState"
+  | "showContextStrip"
+  | "restingControlsRef"
+  | "onLayoutChange"
+>) {
+  const overlayRef = useRef<HTMLDivElement>(null);
+  const isCollapsed = mode !== "expanded";
+  const previousLayoutKeyRef = useRef(layoutKey);
+  const lastLayoutRef = useRef<{
+    key: string | null;
+    layout: ComposerFrameLayout;
+  } | null>(null);
+  const publishLayout = useCallback(
+    (height: number) => {
+      const visibleHeight = Math.ceil(height);
+      if (visibleHeight <= 0 || !Number.isFinite(visibleHeight)) return;
+      const previous = lastLayoutRef.current;
+      const reservedHeight = resolveComposerTimelineInset({
+        currentInset: previous?.key === layoutKey ? previous.layout.reservedHeight : 0,
+        overlayHeight: visibleHeight,
+        isResting: mode === "resting",
+      });
+      if (
+        previous?.key === layoutKey &&
+        previous.layout.mode === mode &&
+        previous.layout.visibleHeight === visibleHeight &&
+        previous.layout.reservedHeight === reservedHeight
+      ) {
+        return;
+      }
+      const layout = { mode, visibleHeight, reservedHeight };
+      lastLayoutRef.current = { key: layoutKey, layout };
+      onLayoutChange(layout);
+    },
+    [layoutKey, mode, onLayoutChange],
+  );
+  const previousCollapsedRef = useRef(isCollapsed);
+  const previousHeightRef = useRef<number | null>(null);
+  const previousContentOffsetsRef = useRef<{
+    promptFromTop: number | null;
+    promptHeight: number | null;
+    actionFromBottom: number | null;
+  }>({ promptFromTop: null, promptHeight: null, actionFromBottom: null });
+  const animationRef = useRef<Animation | null>(null);
+  const animationTargetHeightRef = useRef<number | null>(null);
+  const contentAnimationsRef = useRef<Animation[]>([]);
+  const stateChangeAnimationsRef = useRef<Animation[]>([]);
+  const pinnedOverlayRef = useRef<HTMLElement | null>(null);
+  const transitionCleanupTimeoutRef = useRef<number | null>(null);
+  const transitionLayoutRequestRef = useRef(0);
+  const hasCompletedInitialLayoutRef = useRef(false);
+
+  const clearOverlayPin = useCallback(() => {
+    // Keep the pinned element available through ref detachment on unmount.
+    const overlay = pinnedOverlayRef.current;
+    pinnedOverlayRef.current = null;
+    overlay?.style.removeProperty("height");
+    overlay?.style.removeProperty("display");
+    overlay?.style.removeProperty("flex-direction");
+    overlay?.style.removeProperty("justify-content");
+  }, []);
+
+  const clearTransitionStyles = useCallback(() => {
+    const element = overlayRef.current?.querySelector<HTMLElement>(
+      '[data-chat-composer-main-surface="true"]',
+    );
+    const footer = element?.querySelector<HTMLElement>('[data-chat-composer-footer="true"]');
+    element?.style.removeProperty("overflow");
+    element
+      ?.querySelector<HTMLElement>('[data-chat-composer-surface="true"]')
+      ?.style.removeProperty("height");
+    footer?.style.removeProperty("position");
+    footer?.style.removeProperty("top");
+    footer?.style.removeProperty("bottom");
+    footer?.style.removeProperty("left");
+    footer?.style.removeProperty("right");
+    footer?.style.removeProperty("height");
+    clearOverlayPin();
+  }, [clearOverlayPin]);
+
+  const transitionToCurrentGeometry = useCallback(
+    (stateChanged: boolean) => {
+      const element = overlayRef.current?.querySelector<HTMLElement>(
+        '[data-chat-composer-main-surface="true"]',
+      );
+      const surface = element?.querySelector<HTMLElement>('[data-chat-composer-surface="true"]');
+      if (!element || !surface) return;
+
+      const nextIsCollapsed = isCollapsed;
+
+      const visibleTransitionElement = (selector: string) =>
+        Array.from(element.querySelectorAll<HTMLElement>(selector)).find(
+          (candidate) => candidate.getClientRects().length > 0,
+        ) ?? null;
+      const prompt = visibleTransitionElement(
+        '[data-testid="composer-editor"], [data-chat-composer-transition-prompt="true"]',
+      );
+      const action = visibleTransitionElement('[data-chat-composer-transition-actions="true"]');
+      const footer = element.querySelector<HTMLElement>('[data-chat-composer-footer="true"]');
+      const interruptedAnimation = animationRef.current;
+      const interruptedPromptTop = interruptedAnimation
+        ? (prompt?.getBoundingClientRect().top ?? null)
+        : null;
+      const interruptedActionTop = interruptedAnimation
+        ? (action?.getBoundingClientRect().top ?? null)
+        : null;
+      const interruptedHeight = interruptedAnimation
+        ? element.getBoundingClientRect().height
+        : null;
+      const interruptedTargetHeight = animationTargetHeightRef.current;
+      const interruptedCurrentTime =
+        typeof interruptedAnimation?.currentTime === "number"
+          ? interruptedAnimation.currentTime
+          : null;
+      const interruptedDuration = interruptedAnimation?.effect?.getComputedTiming().duration;
+      if (transitionCleanupTimeoutRef.current !== null) {
+        window.clearTimeout(transitionCleanupTimeoutRef.current);
+        transitionCleanupTimeoutRef.current = null;
+      }
+      interruptedAnimation?.cancel();
+      animationRef.current = null;
+      for (const animation of contentAnimationsRef.current) animation.cancel();
+      contentAnimationsRef.current = [];
+      // The reveal and fade animations keep their own schedule across the
+      // body-resize re-entries that retarget the geometry mid-flight (every
+      // transition with a draft triggers one); cancelling them there would
+      // pop their subjects to full visibility at the start of the tween.
+      if (stateChanged) {
+        for (const animation of stateChangeAnimationsRef.current) animation.cancel();
+        stateChangeAnimationsRef.current = [];
+      }
+      clearTransitionStyles();
+
+      const nextRect = element.getBoundingClientRect();
+      const nextHeight = nextRect.height;
+      // Publish the destination once. The frame stays at this height during
+      // the animation, so consumers do not update on every animation frame.
+      const overlay = overlayRef.current;
+      const overlayHeight = overlay?.getBoundingClientRect().height ?? null;
+      if (overlayHeight !== null) {
+        publishLayout(overlayHeight);
+      }
+      const nextPromptRect = prompt?.getBoundingClientRect() ?? null;
+      const nextPromptTop = nextPromptRect?.top ?? null;
+      const nextActionTop = action?.getBoundingClientRect().top ?? null;
+      const previousHeight = interruptedHeight ?? previousHeightRef.current;
+      const targetChanged =
+        interruptedTargetHeight === null || Math.abs(interruptedTargetHeight - nextHeight) >= 0.5;
+      const prefersReducedMotion = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+      const shouldAnimate = shouldAnimateComposerRestingTransition({
+        hasCompletedInitialLayout: hasCompletedInitialLayoutRef.current,
+        stateChanged,
+        hasInterruptedAnimation: interruptedHeight !== null,
+      });
+
+      if (
+        shouldAnimate &&
+        !prefersReducedMotion &&
+        previousHeight !== null &&
+        Math.abs(previousHeight - nextHeight) >= 0.5
+      ) {
+        const remainingDuration =
+          typeof interruptedDuration === "number" && interruptedCurrentTime !== null
+            ? Math.max(1, interruptedDuration - interruptedCurrentTime)
+            : COMPOSER_RESTING_TRANSITION_DURATION_MS;
+        const duration =
+          interruptedHeight !== null && !targetChanged
+            ? remainingDuration
+            : COMPOSER_RESTING_TRANSITION_DURATION_MS;
+        element.style.overflow = "clip";
+        surface.style.height = "100%";
+
+        // Pinning the overlay at the destination height keeps the resize
+        // observer quiet for the tween; bottom alignment keeps the animating
+        // surface glued to the overlay's stable bottom edge. The pin lasts
+        // only for the tween so later attachment, thread, font, and viewport
+        // changes remain natural.
+        if (overlay && overlayHeight !== null) {
+          overlay.style.height = `${String(overlayHeight)}px`;
+          overlay.style.display = "flex";
+          overlay.style.flexDirection = "column";
+          overlay.style.justifyContent = "flex-end";
+          pinnedOverlayRef.current = overlay;
+        }
+
+        // Keep the footer attached to the stable bottom edge while the outer
+        // height changes. Its resting absolute layout otherwise spans the old
+        // height on collapse, while its expanded flow layout falls below the
+        // clipped surface on expansion.
+        if (footer) {
+          footer.style.position = "absolute";
+          footer.style.top = "auto";
+          footer.style.bottom = "1px";
+          footer.style.height = "3rem";
+          if (nextIsCollapsed) {
+            footer.style.left = "auto";
+            footer.style.right = "1px";
+          } else {
+            footer.style.left = "1px";
+            footer.style.right = "1px";
+          }
+        }
+
+        const animation = element.animate(
+          [{ height: `${previousHeight}px` }, { height: `${nextHeight}px` }],
+          {
+            duration,
+            easing: COMPOSER_RESTING_TRANSITION_EASING,
+          },
+        );
+        animationRef.current = animation;
+        animationTargetHeightRef.current = nextHeight;
+
+        const animatedRect = element.getBoundingClientRect();
+        const previousPromptTop =
+          interruptedPromptTop ??
+          (previousContentOffsetsRef.current.promptFromTop === null
+            ? null
+            : animatedRect.top + previousContentOffsetsRef.current.promptFromTop);
+        const previousActionTop =
+          interruptedActionTop ??
+          (previousContentOffsetsRef.current.actionFromBottom === null
+            ? null
+            : animatedRect.bottom - previousContentOffsetsRef.current.actionFromBottom);
+        const contentAnimations: Animation[] = [];
+        const animateContentPosition = (
+          content: HTMLElement | null,
+          previousTop: number | null,
+        ) => {
+          if (!content || previousTop === null) return;
+          const offset = previousTop - content.getBoundingClientRect().top;
+          if (Math.abs(offset) < 0.5) return;
+          contentAnimations.push(
+            content.animate(
+              [{ transform: `translateY(${String(offset)}px)` }, { transform: "none" }],
+              {
+                duration,
+                easing: COMPOSER_RESTING_TRANSITION_EASING,
+              },
+            ),
+          );
+        };
+        animateContentPosition(prompt, previousPromptTop);
+        animateContentPosition(action, previousActionTop);
+        contentAnimationsRef.current = contentAnimations;
+
+        if (stateChanged) {
+          const stateChangeAnimations: Animation[] = [];
+
+          // A prompt that gains lines on expansion would otherwise slide up
+          // from under the footer band as one block. Opening a bottom clip in
+          // step with the tween instead unfurls the extra lines beneath the
+          // rising first line, so no text crosses the returning controls.
+          const previousPromptHeight = previousContentOffsetsRef.current.promptHeight;
+          if (
+            !nextIsCollapsed &&
+            prompt &&
+            nextPromptRect &&
+            previousPromptHeight !== null &&
+            nextPromptRect.height - previousPromptHeight >= 0.5
+          ) {
+            const hiddenHeight = nextPromptRect.height - previousPromptHeight;
+            stateChangeAnimations.push(
+              prompt.animate(
+                [
+                  { clipPath: `inset(0 0 ${String(hiddenHeight)}px 0)` },
+                  { clipPath: "inset(0 0 0 0)" },
+                ],
+                {
+                  duration,
+                  easing: COMPOSER_RESTING_TRANSITION_EASING,
+                },
+              ),
+            );
+          }
+
+          // The footer controls teleport between the composer footer and the
+          // context strip below it in a single commit. Fading the arriving
+          // cluster in along its direction of travel reads as one continuous
+          // move instead of a pop. Collapsing controls land in empty strip
+          // space and can appear immediately, but expanding controls return
+          // to the bottom row the prompt still occupies while the surface is
+          // short, so they stay hidden through the first half of the tween
+          // and fade in once the geometry has mostly settled.
+          const arrivingControls = nextIsCollapsed
+            ? restingControlsRef.current
+            : element.querySelector<HTMLElement>('[data-chat-composer-controls="left"]');
+          if (arrivingControls) {
+            const drift = nextIsCollapsed
+              ? -COMPOSER_RESTING_CONTROLS_ARRIVAL_DRIFT_PX
+              : COMPOSER_RESTING_CONTROLS_ARRIVAL_DRIFT_PX;
+            stateChangeAnimations.push(
+              arrivingControls.animate(
+                [
+                  { opacity: 0, transform: `translateY(${String(drift)}px)` },
+                  { opacity: 1, transform: "none" },
+                ],
+                {
+                  duration: nextIsCollapsed ? duration : duration / 2,
+                  delay: nextIsCollapsed ? 0 : duration / 2,
+                  fill: "backwards",
+                  easing: COMPOSER_RESTING_TRANSITION_EASING,
+                },
+              ),
+            );
+          }
+
+          const arrivingImagePreviews = nextIsCollapsed
+            ? Array.from(
+                element.querySelectorAll<HTMLElement>('[data-chat-composer-resting-images="true"]'),
+              )
+            : Array.from(
+                element.querySelectorAll<HTMLElement>('[data-chat-composer-expanded-image="true"]'),
+              );
+          for (const imagePreview of arrivingImagePreviews) {
+            stateChangeAnimations.push(
+              imagePreview.animate([{ opacity: 0 }, { opacity: 1 }], {
+                duration: nextIsCollapsed ? duration : duration / 2,
+                delay: nextIsCollapsed ? 0 : duration / 2,
+                fill: "backwards",
+                easing: COMPOSER_RESTING_TRANSITION_EASING,
+              }),
+            );
+          }
+          stateChangeAnimationsRef.current = stateChangeAnimations;
+        }
+
+        const finishTransition = (cancelAnimations: boolean) => {
+          if (animationRef.current !== animation) return;
+          if (transitionCleanupTimeoutRef.current !== null) {
+            window.clearTimeout(transitionCleanupTimeoutRef.current);
+            transitionCleanupTimeoutRef.current = null;
+          }
+          if (cancelAnimations) {
+            animation.cancel();
+            for (const contentAnimation of contentAnimationsRef.current) {
+              contentAnimation.cancel();
+            }
+            for (const stateChangeAnimation of stateChangeAnimationsRef.current) {
+              stateChangeAnimation.cancel();
+            }
+          }
+          animationRef.current = null;
+          animationTargetHeightRef.current = null;
+          contentAnimationsRef.current = [];
+          stateChangeAnimationsRef.current = [];
+          clearTransitionStyles();
+        };
+        void animation.finished.catch(() => undefined).then(() => finishTransition(false));
+        // A suspended document timeline can leave `finished` pending while
+        // these measurement styles remain active. Wall-clock cleanup makes
+        // the natural layout the eventual source of truth in that case.
+        transitionCleanupTimeoutRef.current = window.setTimeout(
+          () => finishTransition(true),
+          duration + COMPOSER_RESTING_TRANSITION_CLEANUP_BUFFER_MS,
+        );
+      } else {
+        animationTargetHeightRef.current = null;
+      }
+
+      previousCollapsedRef.current = nextIsCollapsed;
+      previousHeightRef.current = nextHeight;
+      previousContentOffsetsRef.current = {
+        promptFromTop: nextPromptTop === null ? null : nextPromptTop - nextRect.top,
+        promptHeight: nextPromptRect?.height ?? null,
+        actionFromBottom: nextActionTop === null ? null : nextRect.bottom - nextActionTop,
+      };
+    },
+    [clearTransitionStyles, isCollapsed, publishLayout, restingControlsRef],
+  );
+
+  const stopTransition = useCallback(() => {
+    if (transitionCleanupTimeoutRef.current !== null) {
+      window.clearTimeout(transitionCleanupTimeoutRef.current);
+      transitionCleanupTimeoutRef.current = null;
+    }
+    animationRef.current?.cancel();
+    animationRef.current = null;
+    animationTargetHeightRef.current = null;
+    for (const animation of contentAnimationsRef.current) animation.cancel();
+    contentAnimationsRef.current = [];
+    for (const animation of stateChangeAnimationsRef.current) animation.cancel();
+    stateChangeAnimationsRef.current = [];
+    clearTransitionStyles();
+  }, [clearTransitionStyles]);
+
+  useLayoutEffect(() => {
+    if (previousLayoutKeyRef.current !== layoutKey) {
+      previousLayoutKeyRef.current = layoutKey;
+      stopTransition();
+      previousHeightRef.current = null;
+      previousCollapsedRef.current = isCollapsed;
+    }
+    // The first inset lets the timeline decide whether it overflows before
+    // initial geometry settles. Otherwise that feedback looks like a later
+    // user collapse and animates a newly opened thread.
+    if (lastLayoutRef.current?.key !== layoutKey && overlayRef.current) {
+      publishLayout(overlayRef.current.getBoundingClientRect().height);
+    }
+    const requestId = transitionLayoutRequestRef.current + 1;
+    transitionLayoutRequestRef.current = requestId;
+    const stateChanged = previousCollapsedRef.current !== isCollapsed;
+    // Resting controls can bring the context strip into flow in this commit.
+    // Read the final geometry after those layout updates and before paint.
+    queueMicrotask(() => {
+      if (transitionLayoutRequestRef.current !== requestId) return;
+      transitionToCurrentGeometry(stateChanged);
+    });
+    return () => {
+      if (transitionLayoutRequestRef.current === requestId) {
+        transitionLayoutRequestRef.current += 1;
+      }
+    };
+  }, [
+    isCollapsed,
+    // eslint-disable-next-line react/exhaustive-effect-dependencies -- Hero and context strip changes alter the measured CSS geometry.
+    isDraftHeroState,
+    layoutKey,
+    publishLayout,
+    showContextStrip,
+    stopTransition,
+    transitionToCurrentGeometry,
+  ]);
+
+  useLayoutEffect(() => {
+    const overlay = overlayRef.current;
+    const element = overlay?.querySelector<HTMLElement>('[data-chat-composer-main-surface="true"]');
+    if (!overlay || !element || typeof ResizeObserver === "undefined") return;
+
+    const body = element.querySelector<HTMLElement>('[data-chat-composer-body="true"]');
+    const observer = new ResizeObserver((entries) => {
+      if (animationRef.current) {
+        if (body && entries.some((entry) => entry.target === body)) {
+          transitionToCurrentGeometry(false);
+        }
+        return;
+      }
+      const elementRect = element.getBoundingClientRect();
+      const visibleTransitionElement = (selector: string) =>
+        Array.from(element.querySelectorAll<HTMLElement>(selector)).find(
+          (candidate) => candidate.getClientRects().length > 0,
+        ) ?? null;
+      const promptRect = visibleTransitionElement(
+        '[data-testid="composer-editor"], [data-chat-composer-transition-prompt="true"]',
+      )?.getBoundingClientRect();
+      const actionTop = visibleTransitionElement(
+        '[data-chat-composer-transition-actions="true"]',
+      )?.getBoundingClientRect().top;
+      publishLayout(overlay.getBoundingClientRect().height);
+      previousHeightRef.current = elementRect.height;
+      previousContentOffsetsRef.current = {
+        promptFromTop: promptRect === undefined ? null : promptRect.top - elementRect.top,
+        promptHeight: promptRect?.height ?? null,
+        actionFromBottom: actionTop === undefined ? null : elementRect.bottom - actionTop,
+      };
+    });
+    observer.observe(overlay);
+    observer.observe(element);
+    if (body) observer.observe(body);
+    return () => observer.disconnect();
+  }, [publishLayout, transitionToCurrentGeometry]);
+
+  useEffect(() => {
+    // Host discovery and width measurement settle through layout updates on
+    // mount. Treat that bootstrap as initial geometry so an existing thread
+    // paints at rest instead of visibly collapsing from the expanded height.
+    hasCompletedInitialLayoutRef.current = true;
+    return stopTransition;
+  }, [stopTransition]);
+
+  return overlayRef;
+}
+
+/** Owns the overlay, its resting transition, and the timeline reservation. */
+export function ComposerFrame({
+  children,
+  mode,
+  layoutKey,
+  isDraftHeroState,
+  headline,
+  contextStrip,
+  showContextStrip,
+  transitionGroupRef,
+  composerAnchorRef,
+  viewTransitionName,
+  restingControlsRef,
+  onLayoutChange,
+}: ComposerFrameProps) {
+  const overlayRef = useComposerFrameLayout({
+    mode,
+    layoutKey,
+    isDraftHeroState,
+    showContextStrip,
+    restingControlsRef,
+    onLayoutChange,
+  });
+  return (
+    <div
+      ref={overlayRef}
+      data-chat-composer-overlay="true"
+      className={
+        isDraftHeroState
+          ? "pointer-events-none absolute inset-0 z-20 flex items-center"
+          : "pointer-events-none absolute inset-x-0 bottom-0 z-20 pt-1.5 sm:pt-2"
+      }
+    >
+      <div
+        ref={transitionGroupRef}
+        className="w-full ps-[calc(env(safe-area-inset-left)+0.75rem)] pe-[calc(env(safe-area-inset-right)+0.75rem)] sm:ps-[calc(env(safe-area-inset-left)+1.25rem)] sm:pe-[calc(env(safe-area-inset-right)+1.25rem)]"
+      >
+        <div className="group/composer-stack pointer-events-auto relative z-10">
+          {headline}
+          <div className="relative" style={viewTransitionName ? { viewTransitionName } : undefined}>
+            <ComposerSurface.Shell contextStrip={showContextStrip}>
+              <ComposerSurface.Host>
+                <div ref={composerAnchorRef} className="relative z-10">
+                  {children}
+                </div>
+              </ComposerSurface.Host>
+              {contextStrip}
+            </ComposerSurface.Shell>
+            <div
+              aria-hidden
+              className="h-[calc(env(safe-area-inset-bottom)+1rem)] sm:h-[calc(env(safe-area-inset-bottom)+1.25rem)]"
+            />
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}