From 62d4c2a33fef9209b5659dbc41a86ceb297994f9 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Mon, 25 May 2026 16:17:23 -0500
Subject: [PATCH] =?UTF-8?q?=F0=9F=A4=96=20refactor:=20encode=20chat=20layo?=
 =?UTF-8?q?ut=20lanes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Centralize transcript-tail and composer-decoration layout policy behind semantic lane wrappers. Require layout chrome entries to use lane-specific factories so future banners must explicitly choose whether they belong inside the transcript scrollport or in stable composer chrome.

---

_Generated with `mux` • Model: `openai:gpt-5.5` • Thinking: `xhigh` • Cost: `$0.56`_

<!-- mux-attribution: model=openai:gpt-5.5 thinking=xhigh costs=0.56 -->
---
 src/browser/components/ChatPane/ChatPane.tsx  | 108 +++++++------
 .../ChatPane/LayoutStackLane.test.tsx         | 146 +++++++-----------
 .../components/ChatPane/LayoutStackLane.tsx   |  90 +++++++----
 .../components/ChatPane/layoutStack.ts        |  34 +++-
 4 files changed, 215 insertions(+), 163 deletions(-)

diff --git a/src/browser/components/ChatPane/ChatPane.tsx b/src/browser/components/ChatPane/ChatPane.tsx
index 12a7b27cdc..df834a58de 100644
--- a/src/browser/components/ChatPane/ChatPane.tsx
+++ b/src/browser/components/ChatPane/ChatPane.tsx
@@ -20,8 +20,13 @@ import { EditCutoffBarrier } from "@/browser/features/Messages/ChatBarrier/EditC
 import { StreamingBarrier } from "@/browser/features/Messages/ChatBarrier/StreamingBarrier";
 import { RetryBarrier } from "@/browser/features/Messages/ChatBarrier/RetryBarrier";
 import { PinnedTodoList } from "../PinnedTodoList/PinnedTodoList";
-import { LayoutStackLane } from "./LayoutStackLane";
-import type { LayoutStackItem } from "./layoutStack";
+import { ChatInputDecorationStackLane, TranscriptTailStackLane } from "./LayoutStackLane";
+import {
+  createChatInputDecorationStackItem,
+  createTranscriptTailStackItem,
+  type ChatInputDecorationStackItem,
+  type TranscriptTailStackItem,
+} from "./layoutStack";
 import { VIM_ENABLED_KEY } from "@/common/constants/storage";
 import { ChatInput, type ChatInputAPI } from "@/browser/features/ChatInput/index";
 import type { QueueDispatchMode } from "@/browser/features/ChatInput/types";
@@ -912,42 +917,48 @@ const ChatPaneContent: React.FC<ChatPaneContentProps> = (props) => {
       interruptedBarrierMessageIds.add(message.id);
     }
   }
-  const transcriptTailItems: LayoutStackItem[] = [];
+  const transcriptTailItems: TranscriptTailStackItem[] = [];
   if (shouldMountRetryBarrier) {
-    transcriptTailItems.push({
-      key: "retry-barrier",
-      node: <RetryBarrier workspaceId={workspaceId} visible={showRetryBarrierUI} />,
-    });
+    transcriptTailItems.push(
+      createTranscriptTailStackItem({
+        key: "retry-barrier",
+        node: <RetryBarrier workspaceId={workspaceId} visible={showRetryBarrierUI} />,
+      })
+    );
   }
   if (shouldShowStreamingBarrier) {
-    transcriptTailItems.push({
-      key: "streaming-barrier",
-      node: (
-        <StreamingBarrier
-          workspaceId={workspaceId}
-          vimEnabled={vimEnabled}
-          onCancelCompaction={handleCancelCompactionFromBarrier}
-        />
-      ),
-    });
+    transcriptTailItems.push(
+      createTranscriptTailStackItem({
+        key: "streaming-barrier",
+        node: (
+          <StreamingBarrier
+            workspaceId={workspaceId}
+            vimEnabled={vimEnabled}
+            onCancelCompaction={handleCancelCompactionFromBarrier}
+          />
+        ),
+      })
+    );
   }
   if (shouldShowQueuedAgentTaskPrompt) {
-    transcriptTailItems.push({
-      key: "queued-agent-prompt",
-      node: (
-        <div className="mt-4 mb-1 ml-auto w-fit max-w-full">
-          <div className="rounded-lg border border-[var(--color-user-border)] bg-[var(--color-user-surface)] px-3 py-2 text-sm">
-            <div className="text-muted mb-1 text-[11px] font-medium">Queued</div>
-            <MarkdownRenderer
-              content={queuedAgentTaskPrompt ?? ""}
-              className="user-message-markdown text-foreground"
-              preserveLineBreaks
-              style={{ overflowWrap: "break-word", wordBreak: "break-word" }}
-            />
+    transcriptTailItems.push(
+      createTranscriptTailStackItem({
+        key: "queued-agent-prompt",
+        node: (
+          <div className="mt-4 mb-1 ml-auto w-fit max-w-full">
+            <div className="rounded-lg border border-[var(--color-user-border)] bg-[var(--color-user-surface)] px-3 py-2 text-sm">
+              <div className="text-muted mb-1 text-[11px] font-medium">Queued</div>
+              <MarkdownRenderer
+                content={queuedAgentTaskPrompt ?? ""}
+                className="user-message-markdown text-foreground"
+                preserveLineBreaks
+                style={{ overflowWrap: "break-word", wordBreak: "break-word" }}
+              />
+            </div>
           </div>
-        </div>
-      ),
-    });
+        ),
+      })
+    );
   }
   const handleLoadOlderHistory = useCallback(() => {
     if (!shouldRenderLoadOlderMessagesButton || loadingOlderHistory) {
@@ -1190,12 +1201,9 @@ const ChatPaneContent: React.FC<ChatPaneContentProps> = (props) => {
                   </MessageListProvider>
                 </BashCollapsedSummaryModeProvider>
               )}
-              <LayoutStackLane
+              <TranscriptTailStackLane
                 workspaceId={workspaceId}
                 isHydrating={isHydratingTranscript}
-                align="start"
-                overflowAnchor="none"
-                dataComponent="TranscriptTailStack"
                 items={transcriptTailItems}
               />
             </div>
@@ -1314,9 +1322,13 @@ const ChatInputPane: React.FC<ChatInputPaneProps> = (props) => {
   // Keep optional banners/warnings on one shared lane so the seam right above the textarea is
   // owned by a single component boundary. That lets hydration reserve only the volatile
   // workspace-specific decoration stack instead of the whole composer pane.
-  const decorationEntries: LayoutStackItem[] = [];
+  const decorationEntries: ChatInputDecorationStackItem[] = [];
+  const addDecorationEntry = (entry: { key: string; node: React.ReactNode }) => {
+    decorationEntries.push(createChatInputDecorationStackItem(entry));
+  };
+
   if (props.shouldShowCompactionWarning) {
-    decorationEntries.push({
+    addDecorationEntry({
       key: "compaction-warning",
       node: (
         <CompactionWarning
@@ -1328,7 +1340,7 @@ const ChatInputPane: React.FC<ChatInputPaneProps> = (props) => {
     });
   }
   if (props.contextSwitchWarning) {
-    decorationEntries.push({
+    addDecorationEntry({
       key: "context-switch-warning",
       node: (
         <ContextSwitchWarningBanner
@@ -1344,7 +1356,7 @@ const ChatInputPane: React.FC<ChatInputPaneProps> = (props) => {
   // visibly flashed while another local agent was active. Pin it with composer decorations
   // instead; new transcript rows no longer move the warning.
   if (props.concurrentLocalStreamingWorkspaceName) {
-    decorationEntries.push({
+    addDecorationEntry({
       key: "concurrent-local-warning",
       node: (
         <ConcurrentLocalWarningDecoration
@@ -1355,30 +1367,30 @@ const ChatInputPane: React.FC<ChatInputPaneProps> = (props) => {
   }
 
   if (props.shouldShowPinnedTodoList) {
-    decorationEntries.push({
+    addDecorationEntry({
       key: "pinned-todo-list",
       node: <PinnedTodoList workspaceId={props.workspaceId} />,
     });
   }
-  decorationEntries.push({
+  addDecorationEntry({
     key: "background-processes",
     node: <BackgroundProcessesBanner workspaceId={props.workspaceId} />,
   });
   // The Chat Instructions decoration is intentionally self-gating: it renders
   // nothing when the scratchpad is empty or disabled, so it can always be in
   // the decoration lane without affecting layout for users who don't use it.
-  decorationEntries.push({
+  addDecorationEntry({
     key: "chat-instructions",
     node: <ChatInstructionsChatDecoration workspaceId={props.workspaceId} />,
   });
   if (props.shouldShowReviewsBanner) {
-    decorationEntries.push({
+    addDecorationEntry({
       key: "reviews-banner",
       node: <ReviewsBanner workspaceId={props.workspaceId} />,
     });
   }
   if (props.queuedMessage) {
-    decorationEntries.push({
+    addDecorationEntry({
       key: "queued-message",
       node: (
         <QueuedMessage
@@ -1390,7 +1402,7 @@ const ChatInputPane: React.FC<ChatInputPaneProps> = (props) => {
     });
   }
   if (props.isQueuedAgentTask) {
-    decorationEntries.push({
+    addDecorationEntry({
       key: "queued-agent-task",
       node: (
         <div className="border-border-medium bg-background-secondary text-muted rounded-md border px-3 py-2 text-xs">
@@ -1404,11 +1416,9 @@ const ChatInputPane: React.FC<ChatInputPaneProps> = (props) => {
 
   return (
     <>
-      <LayoutStackLane
+      <ChatInputDecorationStackLane
         workspaceId={props.workspaceId}
         isHydrating={props.isHydratingTranscript}
-        align="end"
-        dataComponent="ChatInputDecorationStack"
         items={decorationEntries}
       />
       <ChatInput
diff --git a/src/browser/components/ChatPane/LayoutStackLane.test.tsx b/src/browser/components/ChatPane/LayoutStackLane.test.tsx
index aa4fe44904..3e9bf403f8 100644
--- a/src/browser/components/ChatPane/LayoutStackLane.test.tsx
+++ b/src/browser/components/ChatPane/LayoutStackLane.test.tsx
@@ -2,12 +2,19 @@ import { afterEach, beforeEach, describe, expect, it } from "bun:test";
 import { cleanup, render, waitFor } from "@testing-library/react";
 import { installDom } from "../../../../tests/ui/dom";
 
-import { LayoutStackLane } from "./LayoutStackLane";
-import type { LayoutStackItem } from "./layoutStack";
+import { ChatInputDecorationStackLane, TranscriptTailStackLane } from "./LayoutStackLane";
+import {
+  createChatInputDecorationStackItem,
+  createTranscriptTailStackItem,
+  type ChatInputDecorationStackItem,
+  type TranscriptTailStackItem,
+} from "./layoutStack";
 
 let cleanupDom: (() => void) | null = null;
 let originalResizeObserver: typeof ResizeObserver | undefined;
 const resizeCallbacks = new Map<Element, ResizeObserverCallback[]>();
+const COMPOSER_STACK_COMPONENT = "ChatInputDecorationStack";
+const TRANSCRIPT_TAIL_STACK_COMPONENT = "TranscriptTailStack";
 
 class ResizeObserverMock implements ResizeObserver {
   public readonly callback: ResizeObserverCallback;
@@ -99,12 +106,16 @@ async function waitForResizeObservation(target: Element): Promise<void> {
   });
 }
 
-function createTextItem(key: string, text: string): LayoutStackItem {
-  return { key, node: <div>{text}</div> };
+function createTextItem(key: string, text: string): ChatInputDecorationStackItem {
+  return createChatInputDecorationStackItem({ key, node: <div>{text}</div> });
 }
 
-function createHiddenItem(key = "idle-decoration"): LayoutStackItem {
-  return { key, node: <span hidden /> };
+function createHiddenItem(key = "idle-decoration"): ChatInputDecorationStackItem {
+  return createChatInputDecorationStackItem({ key, node: <span hidden /> });
+}
+
+function createTranscriptTextItem(key: string, text: string): TranscriptTailStackItem {
+  return createTranscriptTailStackItem({ key, node: <div>{text}</div> });
 }
 
 describe("LayoutStackLane", () => {
@@ -134,239 +145,202 @@ describe("LayoutStackLane", () => {
 
   it("holds the last measured height while switching to a hydrating workspace", async () => {
     const view = render(
-      <LayoutStackLane
+      <ChatInputDecorationStackLane
         workspaceId="workspace-a"
         isHydrating={false}
-        align="end"
-        dataComponent="stable-stack"
         items={[createTextItem("workspace-a", "workspace A")]}
       />
     );
 
-    const content = getStackContent(view.container, "stable-stack");
+    const content = getStackContent(view.container, COMPOSER_STACK_COMPONENT);
     await waitForResizeObservation(content);
     emitResize(content, 184);
 
     view.rerender(
-      <LayoutStackLane
-        workspaceId="workspace-b"
-        isHydrating={true}
-        align="end"
-        dataComponent="stable-stack"
-        items={[]}
-      />
+      <ChatInputDecorationStackLane workspaceId="workspace-b" isHydrating={true} items={[]} />
     );
 
     await waitFor(() => {
-      expect(getRenderedStack(view.container, "stable-stack").style.minHeight).toBe("184px");
+      expect(getRenderedStack(view.container, COMPOSER_STACK_COMPONENT).style.minHeight).toBe(
+        "184px"
+      );
     });
 
     view.rerender(
-      <LayoutStackLane
+      <ChatInputDecorationStackLane
         workspaceId="workspace-b"
         isHydrating={false}
-        align="end"
-        dataComponent="stable-stack"
         items={[createTextItem("workspace-b", "workspace B")]}
       />
     );
 
     await waitFor(() => {
-      expect(getRenderedStack(view.container, "stable-stack").style.minHeight).toBe("");
+      expect(getRenderedStack(view.container, COMPOSER_STACK_COMPONENT).style.minHeight).toBe("");
     });
   });
 
   it("ignores zero-height observations from non-rendering items during hydration", async () => {
     const view = render(
-      <LayoutStackLane
+      <ChatInputDecorationStackLane
         workspaceId="workspace-a"
         isHydrating={false}
-        align="end"
-        dataComponent="stable-stack"
         items={[createTextItem("workspace-a", "workspace A")]}
       />
     );
 
-    const initialContent = getStackContent(view.container, "stable-stack");
+    const initialContent = getStackContent(view.container, COMPOSER_STACK_COMPONENT);
     await waitForResizeObservation(initialContent);
     emitResize(initialContent, 184);
 
     view.rerender(
-      <LayoutStackLane
+      <ChatInputDecorationStackLane
         workspaceId="workspace-b"
         isHydrating={true}
-        align="end"
-        dataComponent="stable-stack"
         items={[createHiddenItem()]}
       />
     );
 
-    const hydratingContent = getStackContent(view.container, "stable-stack");
+    const hydratingContent = getStackContent(view.container, COMPOSER_STACK_COMPONENT);
     await waitForResizeObservation(hydratingContent);
     emitResize(hydratingContent, 0);
 
     await waitFor(() => {
-      expect(getRenderedStack(view.container, "stable-stack").style.minHeight).toBe("184px");
+      expect(getRenderedStack(view.container, COMPOSER_STACK_COMPONENT).style.minHeight).toBe(
+        "184px"
+      );
     });
 
     view.rerender(
-      <LayoutStackLane
+      <ChatInputDecorationStackLane
         workspaceId="workspace-b"
         isHydrating={false}
-        align="end"
-        dataComponent="stable-stack"
         items={[createHiddenItem()]}
       />
     );
 
     await waitFor(() => {
-      expect(getRenderedStack(view.container, "stable-stack").style.minHeight).toBe("");
+      expect(getRenderedStack(view.container, COMPOSER_STACK_COMPONENT).style.minHeight).toBe("");
     });
 
     view.rerender(
-      <LayoutStackLane
+      <ChatInputDecorationStackLane
         workspaceId="workspace-c"
         isHydrating={true}
-        align="end"
-        dataComponent="stable-stack"
         items={[createHiddenItem()]}
       />
     );
 
     await waitFor(() => {
-      expect(getRenderedStack(view.container, "stable-stack").style.minHeight).toBe("");
+      expect(getRenderedStack(view.container, COMPOSER_STACK_COMPONENT).style.minHeight).toBe("");
     });
   });
 
   it("attaches ResizeObserver when items mount after an empty null lane", async () => {
     const view = render(
-      <LayoutStackLane
-        workspaceId="workspace-a"
-        isHydrating={false}
-        align="end"
-        dataComponent="stable-stack"
-        items={[]}
-      />
+      <ChatInputDecorationStackLane workspaceId="workspace-a" isHydrating={false} items={[]} />
     );
 
-    expect(view.container.querySelector('[data-component="stable-stack"]')).toBeNull();
+    expect(
+      view.container.querySelector(`[data-component="${COMPOSER_STACK_COMPONENT}"]`)
+    ).toBeNull();
 
     view.rerender(
-      <LayoutStackLane
+      <ChatInputDecorationStackLane
         workspaceId="workspace-a"
         isHydrating={false}
-        align="end"
-        dataComponent="stable-stack"
         items={[createTextItem("workspace-a", "workspace A")]}
       />
     );
 
-    const mountedContent = getStackContent(view.container, "stable-stack");
+    const mountedContent = getStackContent(view.container, COMPOSER_STACK_COMPONENT);
     await waitForResizeObservation(mountedContent);
     emitResize(mountedContent, 123);
 
     view.rerender(
-      <LayoutStackLane
-        workspaceId="workspace-b"
-        isHydrating={true}
-        align="end"
-        dataComponent="stable-stack"
-        items={[]}
-      />
+      <ChatInputDecorationStackLane workspaceId="workspace-b" isHydrating={true} items={[]} />
     );
 
     await waitFor(() => {
-      expect(getRenderedStack(view.container, "stable-stack").style.minHeight).toBe("123px");
+      expect(getRenderedStack(view.container, COMPOSER_STACK_COMPONENT).style.minHeight).toBe(
+        "123px"
+      );
     });
   });
 
   it("clears settled empty-lane measurements from both the workspace cache and fallback", async () => {
     const view = render(
-      <LayoutStackLane
+      <ChatInputDecorationStackLane
         workspaceId="workspace-a"
         isHydrating={false}
-        align="end"
-        dataComponent="stable-stack"
         items={[createTextItem("workspace-a", "workspace A")]}
       />
     );
 
-    const initialContent = getStackContent(view.container, "stable-stack");
+    const initialContent = getStackContent(view.container, COMPOSER_STACK_COMPONENT);
     await waitForResizeObservation(initialContent);
     emitResize(initialContent, 184);
 
     view.rerender(
-      <LayoutStackLane
+      <ChatInputDecorationStackLane
         workspaceId="workspace-a"
         isHydrating={false}
-        align="end"
-        dataComponent="stable-stack"
         items={[createHiddenItem()]}
       />
     );
 
-    const settledEmptyContent = getStackContent(view.container, "stable-stack");
+    const settledEmptyContent = getStackContent(view.container, COMPOSER_STACK_COMPONENT);
     await waitForResizeObservation(settledEmptyContent);
     emitResize(settledEmptyContent, 0);
 
     view.rerender(
-      <LayoutStackLane
+      <ChatInputDecorationStackLane
         workspaceId="workspace-a"
         isHydrating={true}
-        align="end"
-        dataComponent="stable-stack"
         items={[createHiddenItem()]}
       />
     );
 
     await waitFor(() => {
-      expect(getRenderedStack(view.container, "stable-stack").style.minHeight).toBe("");
+      expect(getRenderedStack(view.container, COMPOSER_STACK_COMPONENT).style.minHeight).toBe("");
     });
 
     view.rerender(
-      <LayoutStackLane
+      <ChatInputDecorationStackLane
         workspaceId="workspace-b"
         isHydrating={true}
-        align="end"
-        dataComponent="stable-stack"
         items={[createHiddenItem()]}
       />
     );
 
     await waitFor(() => {
-      expect(getRenderedStack(view.container, "stable-stack").style.minHeight).toBe("");
+      expect(getRenderedStack(view.container, COMPOSER_STACK_COMPONENT).style.minHeight).toBe("");
     });
   });
 
-  it("renders alignment and overflow-anchor modifiers correctly", () => {
+  it("renders semantic lane policies correctly", () => {
     const view = render(
       <div>
-        <LayoutStackLane
+        <ChatInputDecorationStackLane
           workspaceId="workspace-a"
           isHydrating={false}
-          align="end"
-          dataComponent="decoration-lane"
           items={[createTextItem("workspace-a", "workspace A")]}
         />
         <div data-component="ChatInputSection">Input</div>
       </div>
     );
 
-    const decoration = getRenderedStack(view.container, "decoration-lane");
+    const decoration = getRenderedStack(view.container, COMPOSER_STACK_COMPONENT);
     expect(decoration.className).toContain("justify-end");
     expect(decoration.style.overflowAnchor).toBe("");
 
     const tail = render(
-      <LayoutStackLane
+      <TranscriptTailStackLane
         workspaceId="workspace-a"
         isHydrating={false}
-        align="start"
-        overflowAnchor="none"
-        dataComponent="tail-lane"
-        items={[createTextItem("workspace-a", "workspace A")]}
+        items={[createTranscriptTextItem("workspace-a", "workspace A")]}
       />
     );
-    const tailStack = getRenderedStack(tail.container, "tail-lane");
+    const tailStack = getRenderedStack(tail.container, TRANSCRIPT_TAIL_STACK_COMPONENT);
     expect(tailStack.className).toContain("justify-start");
     expect(tailStack.style.overflowAnchor).toBe("none");
   });
diff --git a/src/browser/components/ChatPane/LayoutStackLane.tsx b/src/browser/components/ChatPane/LayoutStackLane.tsx
index 99b2ceab02..bd800cb432 100644
--- a/src/browser/components/ChatPane/LayoutStackLane.tsx
+++ b/src/browser/components/ChatPane/LayoutStackLane.tsx
@@ -4,39 +4,65 @@ import {
   getReservedLayoutStackHeightPx,
   measureLayoutStackHeightPx,
   rememberLayoutStackHeight,
-  type LayoutStackItem,
+  type ChatInputDecorationStackItem,
+  type LayoutStackLaneKind,
+  type TranscriptTailStackItem,
 } from "./layoutStack";
 
-/**
- * Shared lane for a stack of layout-affecting transcript chrome. Previously split
- * into `TranscriptTailStack` (top-aligned, scroll-pinning) and
- * `ChatInputDecorationStack` (bottom-aligned, measurement-only) which shared ~85%
- * of their machinery — the per-workspace reserved-height memory, the RO settle
- * dance, and the hydration bookkeeping.
- *
- * Differences are now expressed as props:
- *  - `align` picks between `justify-start` (tail, above the composer's opposite
- *    side of the transcript) and `justify-end` (composer decoration).
- *  - `overflowAnchor="none"` opts the tail lane out of browser scroll anchoring
- *    so a newly-inserted tail row (streaming barrier, etc.) can't win the anchor
- *    heuristic and flash the layout underneath.
- *
- * Height changes are observed by the transcript scroll owner; this lane only
- * handles reservation and alignment.
- */
-interface LayoutStackLaneProps {
-  workspaceId: string;
-  isHydrating: boolean;
-  items: readonly LayoutStackItem[];
+interface LayoutStackLaneConfig {
   align: "start" | "end";
+  dataComponent: string;
   overflowAnchor?: "none";
-  dataComponent?: string;
 }
 
-export const LayoutStackLane: React.FC<LayoutStackLaneProps> = (props) => {
+const LAYOUT_STACK_LANE_CONFIG: Record<LayoutStackLaneKind, LayoutStackLaneConfig> = {
+  "transcript-tail": {
+    align: "start",
+    dataComponent: "TranscriptTailStack",
+    overflowAnchor: "none",
+  },
+  "composer-decoration": {
+    align: "end",
+    dataComponent: "ChatInputDecorationStack",
+  },
+};
+
+interface BaseLayoutStackLaneProps {
+  workspaceId: string;
+  isHydrating: boolean;
+}
+
+interface TranscriptTailStackLaneProps extends BaseLayoutStackLaneProps {
+  items: readonly TranscriptTailStackItem[];
+}
+
+interface ChatInputDecorationStackLaneProps extends BaseLayoutStackLaneProps {
+  items: readonly ChatInputDecorationStackItem[];
+}
+
+type LayoutStackLaneProps =
+  | (TranscriptTailStackLaneProps & { lane: "transcript-tail" })
+  | (ChatInputDecorationStackLaneProps & { lane: "composer-decoration" });
+
+/**
+ * Shared implementation for layout-affecting chat chrome. Public callers choose a
+ * semantic lane through the wrappers below instead of passing low-level layout knobs.
+ *
+ * Lane semantics are intentionally centralized here:
+ *  - transcript tail: content that belongs in the scrollport after messages and
+ *    must opt out of browser scroll anchoring.
+ *  - composer decoration: persistent workspace chrome above the textarea whose
+ *    height changes are handled by the transcript scroll owner from outside the
+ *    scrollport.
+ *
+ * This keeps future warnings/banners from accidentally reintroducing the class of
+ * flash where appending a message moves a live tail row before bottom-lock settles.
+ */
+const LayoutStackLane: React.FC<LayoutStackLaneProps> = (props) => {
   const contentRef = useRef<HTMLDivElement>(null);
   const stackHeightByWorkspaceIdRef = useRef(new Map<string, number>());
   const lastMeasuredStackHeightRef = useRef(0);
+  const laneConfig = LAYOUT_STACK_LANE_CONFIG[props.lane];
 
   const hasItems = props.items.length > 0;
   const reservedStackHeightPx = getReservedLayoutStackHeightPx({
@@ -121,16 +147,16 @@ export const LayoutStackLane: React.FC<LayoutStackLaneProps> = (props) => {
   if (reservedStackHeightPx !== null) {
     style.minHeight = `${reservedStackHeightPx}px`;
   }
-  if (props.overflowAnchor === "none") {
+  if (laneConfig.overflowAnchor === "none") {
     style.overflowAnchor = "none";
   }
 
   return (
     <div
       className={
-        props.align === "end" ? "flex flex-col justify-end" : "flex flex-col justify-start"
+        laneConfig.align === "end" ? "flex flex-col justify-end" : "flex flex-col justify-start"
       }
-      data-component={props.dataComponent}
+      data-component={laneConfig.dataComponent}
       style={style}
     >
       <div ref={contentRef}>
@@ -141,3 +167,13 @@ export const LayoutStackLane: React.FC<LayoutStackLaneProps> = (props) => {
     </div>
   );
 };
+
+export const TranscriptTailStackLane: React.FC<TranscriptTailStackLaneProps> = (props) => {
+  return <LayoutStackLane {...props} lane="transcript-tail" />;
+};
+
+export const ChatInputDecorationStackLane: React.FC<ChatInputDecorationStackLaneProps> = (
+  props
+) => {
+  return <LayoutStackLane {...props} lane="composer-decoration" />;
+};
diff --git a/src/browser/components/ChatPane/layoutStack.ts b/src/browser/components/ChatPane/layoutStack.ts
index 77aa5efcd3..8cd2c7f798 100644
--- a/src/browser/components/ChatPane/layoutStack.ts
+++ b/src/browser/components/ChatPane/layoutStack.ts
@@ -1,10 +1,42 @@
 import type { MutableRefObject, ReactNode } from "react";
 
-export interface LayoutStackItem {
+export type LayoutStackLaneKind = "transcript-tail" | "composer-decoration";
+
+interface LayoutStackItemInit {
   key: string;
   node: ReactNode;
 }
 
+export interface LayoutStackItem<
+  Lane extends LayoutStackLaneKind = LayoutStackLaneKind,
+> extends LayoutStackItemInit {
+  readonly layoutLane: Lane;
+}
+
+export type TranscriptTailStackItem = LayoutStackItem<"transcript-tail">;
+export type ChatInputDecorationStackItem = LayoutStackItem<"composer-decoration">;
+
+function createLayoutStackItem<Lane extends LayoutStackLaneKind>(
+  layoutLane: Lane,
+  item: LayoutStackItemInit
+): LayoutStackItem<Lane> {
+  return { ...item, layoutLane };
+}
+
+// Choosing a factory is the layout contract: transcript-tail items may move the
+// scrollport bottom, while composer decorations live in the stable chrome above
+// the textarea. Making that choice explicit keeps persistent warnings from being
+// accidentally appended inside the transcript again.
+export function createTranscriptTailStackItem(item: LayoutStackItemInit): TranscriptTailStackItem {
+  return createLayoutStackItem("transcript-tail", item);
+}
+
+export function createChatInputDecorationStackItem(
+  item: LayoutStackItemInit
+): ChatInputDecorationStackItem {
+  return createLayoutStackItem("composer-decoration", item);
+}
+
 interface ReservedLayoutStackHeightProps {
   workspaceId: string;
   isHydrating: boolean;