From 55e500f2dc8591971a47b5b562a495b22c2c5f8f Mon Sep 17 00:00:00 2001
From: Krzysztof Wende <wende@hey.com>
Date: Tue, 24 Mar 2026 22:23:38 +0100
Subject: [PATCH 1/4] Preserve host backgrounds for embedded widget

---
 hooks/useAppMode.ts  |  7 ++++++-
 lib/widgetContext.ts |  1 +
 widget.tsx           | 13 ++++++++++---
 3 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/hooks/useAppMode.ts b/hooks/useAppMode.ts
index 6c18f55..8c04d18 100644
--- a/hooks/useAppMode.ts
+++ b/hooks/useAppMode.ts
@@ -73,9 +73,14 @@ export function useAppMode(): AppMode {
     isDetachedRef.current = resolvedMode.isDetached;
     isNativeRef.current = resolvedMode.isNative;
 
-    if (resolvedMode.isDetached) {
+    const shouldUseTransparentHostBackground = widgetCtx?.transparentHostBackground !== false
+
+    if (resolvedMode.isDetached && shouldUseTransparentHostBackground) {
       document.body.style.background = "transparent";
       document.documentElement.style.background = "transparent";
+    } else if (resolvedMode.isDetached) {
+      document.body.style.background = "";
+      document.documentElement.style.background = "";
     }
 
     if (resolvedMode.isNative) {
diff --git a/lib/widgetContext.ts b/lib/widgetContext.ts
index fc42816..7cd9349 100644
--- a/lib/widgetContext.ts
+++ b/lib/widgetContext.ts
@@ -5,6 +5,7 @@ export interface WidgetContextValue {
   noBorder: boolean;
   wsUrl: string | null;
   demo?: boolean;
+  transparentHostBackground?: boolean;
 }
 
 const WidgetContext = createContext<WidgetContextValue | null>(null);
diff --git a/widget.tsx b/widget.tsx
index 1b4feab..63f4637 100644
--- a/widget.tsx
+++ b/widget.tsx
@@ -12,13 +12,20 @@ export interface ChatWidgetProps {
   wsUrl?: string
   className?: string
   demo?: boolean
+  transparentHostBackground?: boolean
 }
 
 export const ChatWidget = forwardRef<ChatInputHandle, ChatWidgetProps>(
-  function ChatWidget({ wsUrl, className, demo }, ref) {
+  function ChatWidget({ wsUrl, className, demo, transparentHostBackground = true }, ref) {
     const modeValue = useMemo(
-      () => ({ isDetached: true, noBorder: true, wsUrl: wsUrl ?? null, demo: demo ?? false }),
-      [wsUrl, demo],
+      () => ({
+        isDetached: true,
+        noBorder: true,
+        wsUrl: wsUrl ?? null,
+        demo: demo ?? false,
+        transparentHostBackground,
+      }),
+      [wsUrl, demo, transparentHostBackground],
     )
 
     return (

From f3fe3ae6fa68bd51af5ee6c9ee936eb1c2060421 Mon Sep 17 00:00:00 2001
From: Krzysztof Wende <wende@hey.com>
Date: Wed, 25 Mar 2026 01:15:24 +0100
Subject: [PATCH 2/4] Add detached mobile Safari document-scroll chat mode

---
 app/globals.css                               |  13 ++
 app/layout.tsx                                |  21 ++-
 app/page.tsx                                  |  53 +++++-
 components/ChatInput.tsx                      |  71 +++++---
 components/chat/ChatComposerBar.tsx           |  62 ++++++-
 components/chat/ChatViewport.tsx              |  91 ++++++----
 ...os-safari-detached-document-scroll-chat.md |  71 ++++++++
 hooks/chat/useOpenClawRuntime.ts              |  19 +-
 hooks/useAppMode.ts                           |   2 +-
 hooks/useIsMobileViewport.ts                  |  25 +++
 hooks/useScrollManager.ts                     | 170 ++++++++++++------
 lib/chat/layout.ts                            |  24 +++
 tests/layout.test.ts                          |  38 +++-
 13 files changed, 539 insertions(+), 121 deletions(-)
 create mode 100644 dev-notes/2026-03-25_ios-safari-detached-document-scroll-chat.md
 create mode 100644 hooks/useIsMobileViewport.ts

diff --git a/app/globals.css b/app/globals.css
index 4b616a9..ccac33b 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -128,6 +128,16 @@
   --color-sidebar-ring: var(--sidebar-ring);
 }
 
+[data-mobileclaw-embedded] {
+  --primary: oklch(0.313 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+}
+
+.dark [data-mobileclaw-embedded] {
+  --primary: oklch(0.258 0 0);
+  --primary-foreground: oklch(0.911 0 0);
+}
+
 @theme {
   /* Font-size scale — boosted so text-sm = 16px body baseline */
   --text-2xs: 0.75rem;            /* 12px */
@@ -148,6 +158,9 @@
   * {
     @apply border-border outline-ring/50;
   }
+  html {
+    @apply bg-background text-foreground;
+  }
   body {
     @apply bg-background text-foreground;
     overflow: hidden;
diff --git a/app/layout.tsx b/app/layout.tsx
index b9f52c8..d9a9301 100644
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -32,9 +32,15 @@ export const metadata: Metadata = {
 // Also registers the service worker for PWA support
 const headScript = `
 (function() {
+  var isDev = ${JSON.stringify(process.env.NODE_ENV !== 'production')};
   var params = new URLSearchParams(location.search);
   var detached = params.has('detached');
   var detachedMode = detached ? params.get('mode') : null;
+  var host = location.hostname;
+  var isIpV4 = /^\\d+\\.\\d+\\.\\d+\\.\\d+$/.test(host);
+  var isLocalHost = host === 'localhost' || host === '127.0.0.1' || host === '0.0.0.0' || host.endsWith('.local');
+  var isPrivateLanIp = /^10\\./.test(host) || /^192\\.168\\./.test(host) || /^172\\.(1[6-9]|2\\d|3[0-1])\\./.test(host);
+  var shouldDisableServiceWorker = isDev || isLocalHost || (isIpV4 && isPrivateLanIp);
   try {
     if (detachedMode === 'dark') {
       document.documentElement.classList.add('dark');
@@ -53,8 +59,19 @@ const headScript = `
   if (detached) {
     document.documentElement.classList.add('detached-loading');
   }
-  if ('serviceWorker' in navigator && location.hostname !== 'localhost' && !window.__nativeMode) {
+  if ('serviceWorker' in navigator && !window.__nativeMode) {
     window.addEventListener('load', function() {
+      if (shouldDisableServiceWorker) {
+        navigator.serviceWorker.getRegistrations().then(function(registrations) {
+          registrations.forEach(function(registration) { registration.unregister(); });
+        });
+        if (window.caches && caches.keys) {
+          caches.keys().then(function(keys) {
+            keys.forEach(function(key) { caches.delete(key); });
+          });
+        }
+        return;
+      }
       navigator.serviceWorker.register('/sw.js');
     });
   }
@@ -67,7 +84,7 @@ export default function RootLayout({
   children: React.ReactNode
 }>) {
   return (
-    <html lang="en" suppressHydrationWarning>
+    <html lang="en" suppressHydrationWarning className="bg-background text-foreground">
       <head>
         <script dangerouslySetInnerHTML={{ __html: headScript }} />
       </head>
diff --git a/app/page.tsx b/app/page.tsx
index 6a77642..227fd59 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -51,6 +51,7 @@ import { useZenMode } from "@mc/hooks/useZenMode";
 import { useSubagentStore } from "@mc/hooks/useSubagentStore";
 import { formatSessionName } from "@mc/hooks/useSessionSwitcher";
 import { useAppMode } from "@mc/hooks/useAppMode";
+import { useIsMobileViewport } from "@mc/hooks/useIsMobileViewport";
 
 import { useModeBootstrap } from "@mc/hooks/chat/useModeBootstrap";
 import { useOpenClawRuntime } from "@mc/hooks/chat/useOpenClawRuntime";
@@ -77,10 +78,31 @@ export default forwardRef<ChatInputHandle>(function Home(_props, forwardedRef) {
   const [streamingId, setStreamingId] = useState<string | null>(null);
   const [sentAnimId, setSentAnimId] = useState<string | null>(null);
   const { isDetached, detachedNoBorder, isNative, uploadDisabled, hideChrome, isDetachedRef, isNativeRef } = useAppMode();
+  const isMobileViewport = useIsMobileViewport();
+  const useDocumentScroll = isDetached && !isNative && isMobileViewport;
+
+  useEffect(() => {
+    if (!useDocumentScroll) return;
+
+    const prevHtmlOverflow = document.documentElement.style.overflow;
+    const prevBodyOverflow = document.body.style.overflow;
+    const prevBodyOverscroll = document.body.style.overscrollBehavior;
+
+    document.documentElement.style.overflow = "visible";
+    document.body.style.overflow = "visible";
+    document.body.style.overscrollBehavior = "auto";
+
+    return () => {
+      document.documentElement.style.overflow = prevHtmlOverflow;
+      document.body.style.overflow = prevBodyOverflow;
+      document.body.style.overscrollBehavior = prevBodyOverscroll;
+    };
+  }, [useDocumentScroll]);
 
   const {
     scrollRef,
     bottomRef,
+    footerReserveRef,
     morphRef,
     scrollPhase,
     pinnedToBottomRef,
@@ -88,7 +110,12 @@ export default forwardRef<ChatInputHandle>(function Home(_props, forwardedRef) {
     handleScroll,
     scrollToBottom,
     updateGraceForStreamingChange,
-  } = useScrollManager(messages, isStreamingRef, isNativeRef);
+  } = useScrollManager({
+    messages,
+    isStreamingRef,
+    isNativeRef,
+    useDocumentScroll,
+  });
 
   const setIsStreaming = useCallback((value: boolean) => {
     const wasStreaming = isStreamingRef.current;
@@ -260,7 +287,7 @@ export default forwardRef<ChatInputHandle>(function Home(_props, forwardedRef) {
     setTurnstileChecked(true);
   }, []);
 
-  useKeyboardLayout(appRef, floatingBarRef, bottomRef, !isNative);
+  useKeyboardLayout(appRef, floatingBarRef, bottomRef, !isNative && !useDocumentScroll);
 
   const appendContentDelta = useCallback((runId: string, delta: string, ts: number) => {
     beginContentArrival();
@@ -361,6 +388,7 @@ export default forwardRef<ChatInputHandle>(function Home(_props, forwardedRef) {
   } = useOpenClawRuntime({
     backendMode,
     isNative,
+    useDocumentScroll,
     isDetachedRef,
     isNativeRef,
     scrollRef,
@@ -702,11 +730,11 @@ export default forwardRef<ChatInputHandle>(function Home(_props, forwardedRef) {
   const bottomPad = getChatBottomPad({
     isNative,
     isDetached,
+    useDocumentScroll,
     inputZoneHeight,
     hasQueued: !!queuedMessage,
     hasPinnedSubagent: !!pinnedSubagent,
   });
-
   const lastUserMessage = useMemo(() => {
     for (let i = messages.length - 1; i >= 0; i--) {
       if (messages[i].role === "user" && !messages[i].isContext) {
@@ -716,6 +744,9 @@ export default forwardRef<ChatInputHandle>(function Home(_props, forwardedRef) {
     return "";
   }, [messages]);
 
+  const showAppBackground = useDocumentScroll || !hideChrome;
+  const shellStyle = useDocumentScroll ? undefined : { height: isDetached ? "100%" : "100dvh" };
+
   if (!turnstileChecked) return null;
   if (!turnstileVerified && TURNSTILE_SITE_KEY) {
     return (
@@ -730,7 +761,11 @@ export default forwardRef<ChatInputHandle>(function Home(_props, forwardedRef) {
   }
 
   return (
-    <div ref={appRef} className={`relative flex flex-col overflow-hidden ${hideChrome ? "" : "bg-background"}`} style={{ height: isDetached ? "100%" : "100dvh" }}>
+    <div
+      ref={appRef}
+      className={`relative flex flex-col ${useDocumentScroll ? "min-h-svh overflow-visible" : "overflow-hidden"} ${showAppBackground ? "bg-background" : ""}`}
+      style={shellStyle}
+    >
       <ChatChrome
         hideChrome={hideChrome}
         openclawUrl={openclawUrl}
@@ -770,6 +805,7 @@ export default forwardRef<ChatInputHandle>(function Home(_props, forwardedRef) {
         isDetached={isDetached}
         detachedNoBorder={detachedNoBorder}
         isNative={isNative}
+        useDocumentScroll={useDocumentScroll}
         historyLoaded={historyLoaded}
         inputZoneHeight={inputZoneHeight}
         bottomPad={bottomPad}
@@ -815,7 +851,9 @@ export default forwardRef<ChatInputHandle>(function Home(_props, forwardedRef) {
       <ChatComposerBar
         isNative={isNative}
         isDetached={isDetached}
+        useDocumentScroll={useDocumentScroll}
         floatingBarRef={floatingBarRef}
+        footerReserveRef={footerReserveRef}
         morphRef={morphRef}
         pinnedSubagent={pinnedSubagent}
         subagentStore={subagentStore}
@@ -848,6 +886,13 @@ export default forwardRef<ChatInputHandle>(function Home(_props, forwardedRef) {
         lastUserMessage={lastUserMessage}
         uploadDisabled={uploadDisabled}
       />
+
+      {useDocumentScroll && (
+        <div
+          aria-hidden="true"
+          style={{ height: "calc(env(safe-area-inset-bottom, 0px) + 10dvh)", flexShrink: 0 }}
+        />
+      )}
     </div>
   );
 });
diff --git a/components/ChatInput.tsx b/components/ChatInput.tsx
index 1e2d543..1d411c4 100644
--- a/components/ChatInput.tsx
+++ b/components/ChatInput.tsx
@@ -23,6 +23,7 @@ export const ChatInput = forwardRef<ChatInputHandle, {
   onSend: (text: string, attachments?: ImageAttachment[]) => void;
   scrollPhase?: "input" | "pill";
   onScrollToBottom?: () => void;
+  disableScrollMorph?: boolean;
   availableModels?: ModelChoice[];
   modelsLoading?: boolean;
   onFetchModels?: () => void;
@@ -41,6 +42,7 @@ export const ChatInput = forwardRef<ChatInputHandle, {
   onSend,
   scrollPhase = "input",
   onScrollToBottom,
+  disableScrollMorph = true,
   availableModels = [],
   modelsLoading = false,
   onFetchModels,
@@ -341,8 +343,9 @@ export const ChatInput = forwardRef<ChatInputHandle, {
     }
   };
 
-  const isPill = scrollPhase === "pill";
+  const isPill = !disableScrollMorph && scrollPhase === "pill";
   const hasContent = !!value.trim() || attachments.length > 0;
+  const staticComposer = disableScrollMorph;
 
   // maps.json is generated by gen_maps.py:
   //   displacement — PNG normal map (R=X, G=Y surface normals for a pill-shaped lens)
@@ -350,7 +353,10 @@ export const ChatInput = forwardRef<ChatInputHandle, {
   const { w: fw, h: fh } = filterDims;
 
   return (
-    <div className="relative">
+    <div
+      className="relative"
+      style={disableScrollMorph ? ({ ["--sp"]: 0, ["--lp"]: 0 } as React.CSSProperties) : undefined}
+    >
       {/* SVG Filters for Liquid Glass */}
       <svg width="0" height="0" className="absolute pointer-events-none">
         <defs>
@@ -472,7 +478,7 @@ export const ChatInput = forwardRef<ChatInputHandle, {
 
       <div
         className="flex items-end justify-center"
-        style={{ gap: "calc(8px * (1 - var(--lp, 0)))" } as React.CSSProperties}
+        style={{ gap: staticComposer ? 8 : "calc(8px * (1 - var(--lp, 0)))" } as React.CSSProperties}
       >
       {/* Image picker button — fades & collapses */}
       <button
@@ -480,9 +486,9 @@ export const ChatInput = forwardRef<ChatInputHandle, {
         onClick={uploadDisabled ? undefined : () => fileInputRef.current?.click()}
         className={`mb-1 flex shrink-0 items-center justify-center rounded-full border border-border bg-card text-muted-foreground transition-[opacity] duration-200 overflow-hidden${uploadDisabled ? " opacity-30 cursor-not-allowed" : " hover:bg-accent hover:text-foreground"}`}
         style={{
-          opacity: uploadDisabled ? 0.3 : "max(0, 1 - var(--sp, 0) * 2.5)",
-          width: "calc(40px * (1 - var(--lp, 0)))",
-          height: "calc(40px * (1 - var(--lp, 0)))",
+          opacity: uploadDisabled ? 0.3 : (staticComposer ? 1 : "max(0, 1 - var(--sp, 0) * 2.5)"),
+          width: staticComposer ? 40 : "calc(40px * (1 - var(--lp, 0)))",
+          height: staticComposer ? 40 : "calc(40px * (1 - var(--lp, 0)))",
           minWidth: 0,
           pointerEvents: isPill ? "none" : "auto",
         } as React.CSSProperties}
@@ -503,10 +509,10 @@ export const ChatInput = forwardRef<ChatInputHandle, {
         tabIndex={isPill ? 0 : undefined}
         onKeyDown={isPill ? (e: React.KeyboardEvent) => { if (e.key === "Enter") onScrollToBottom?.(); } : undefined}
         style={{
-          minHeight: "46px",
-          maxHeight: "calc(200px - 154px * var(--lp, 0))",
+          minHeight: staticComposer ? PILL_BASE_HEIGHT + 2 : `calc(${PILL_BASE_HEIGHT}px + 2px * var(--lp, 0))`,
+          maxHeight: staticComposer ? 200 : `calc(200px - ${200 - (PILL_BASE_HEIGHT + 2)}px * var(--lp, 0))`,
           borderRadius: `${cornerRadius}px`,
-          transition: RADIUS_TRANSITION,
+          transition: staticComposer ? "none" : RADIUS_TRANSITION,
           cursor: isPill ? "pointer" : "text",
           background: isPill
             ? "oklch(from var(--background) l c h / 0.30)"
@@ -522,7 +528,7 @@ export const ChatInput = forwardRef<ChatInputHandle, {
           <div
             className="flex gap-1.5 overflow-x-auto px-3 pt-2.5 pb-1 scrollbar-hide"
             style={{
-              opacity: "calc(1 - var(--sp, 0))",
+              opacity: staticComposer ? 1 : "calc(1 - var(--sp, 0))",
               pointerEvents: isPill ? "none" : "auto",
             } as React.CSSProperties}
           >
@@ -543,21 +549,32 @@ export const ChatInput = forwardRef<ChatInputHandle, {
         )}
 
         {/* Pill overlay */}
-        <div
-          className="absolute inset-0 flex items-center justify-center gap-2 whitespace-nowrap text-xs font-medium"
-          style={{ opacity: "var(--sp, 0)", pointerEvents: isPill ? "auto" : "none", color: "var(--foreground)", filter: "drop-shadow(0 0 8px var(--background))" } as React.CSSProperties}
-        >
-          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className="shrink-0">
-            <path d="m7 13 5 5 5-5" /><path d="M12 18V6" />
-          </svg>
-          <span>Scroll to bottom</span>
-        </div>
+        {!staticComposer && (
+          <div
+            className="absolute inset-0 box-border flex items-center justify-center gap-2 px-4 py-2.5 whitespace-nowrap text-xs leading-[1.75rem] font-normal"
+            style={{
+              opacity: "var(--sp, 0)",
+              pointerEvents: isPill ? "auto" : "none",
+              color: "var(--foreground)",
+              willChange: "opacity",
+            } as React.CSSProperties}
+          >
+            <span
+              className="flex h-4 w-4 shrink-0 items-center justify-center leading-none"
+              aria-hidden="true"
+              style={{ textShadow: "0 0 8px var(--background)", fontSize: "14px", fontWeight: 600 } as React.CSSProperties}
+            >
+              ↓
+            </span>
+            <span style={{ textShadow: "0 0 8px var(--background)" } as React.CSSProperties}>Scroll to bottom</span>
+          </div>
+        )}
 
         {/* Textarea */}
         <div
           className="px-4 py-2.5 flex items-center"
           style={{
-            opacity: "calc(1 - var(--sp, 0))",
+            opacity: staticComposer ? 1 : "calc(1 - var(--sp, 0))",
             pointerEvents: isPill ? "none" : "auto",
           } as React.CSSProperties}
         >
@@ -597,14 +614,16 @@ export const ChatInput = forwardRef<ChatInputHandle, {
             disabled={(!isActive || queueFull) && !isPill}
             className="mb-1 relative shrink-0 rounded-full overflow-hidden active:scale-85"
             style={{
-              opacity: (isActive && !queueFull)
-                ? "max(0, 1 - var(--sp, 0) * 2.5)"
-                : "max(0, (1 - var(--sp, 0) * 2.5) * 0.3)",
-              width: "calc(40px * (1 - var(--sp, 0)))",
-              height: "calc(40px * (1 - var(--sp, 0)))",
+              opacity: staticComposer
+                ? ((isActive && !queueFull) ? 1 : 0.3)
+                : ((isActive && !queueFull)
+                  ? "max(0, 1 - var(--sp, 0) * 2.5)"
+                  : "max(0, (1 - var(--sp, 0) * 2.5) * 0.3)"),
+              width: staticComposer ? 40 : "calc(40px * (1 - var(--sp, 0)))",
+              height: staticComposer ? 40 : "calc(40px * (1 - var(--sp, 0)))",
               minWidth: 0,
               pointerEvents: isPill ? "none" : "auto",
-              transition: (isActive && !queueFull) ? "opacity 200ms, transform 200ms" : "transform 200ms",
+              transition: staticComposer ? "transform 200ms" : ((isActive && !queueFull) ? "opacity 200ms, transform 200ms" : "transform 200ms"),
             } as React.CSSProperties}
             aria-label={showStop ? "Stop" : showQueue ? "Queue" : "Send"}
           >
diff --git a/components/chat/ChatComposerBar.tsx b/components/chat/ChatComposerBar.tsx
index a72c9d8..8cd9581 100644
--- a/components/chat/ChatComposerBar.tsx
+++ b/components/chat/ChatComposerBar.tsx
@@ -12,7 +12,9 @@ import type { BackendMode, ImageAttachment, InputAttachment, ModelChoice } from
 interface ChatComposerBarProps {
   isNative: boolean;
   isDetached: boolean;
+  useDocumentScroll?: boolean;
   floatingBarRef: React.RefObject<HTMLDivElement | null>;
+  footerReserveRef?: React.RefObject<HTMLDivElement | null>;
   morphRef: React.RefObject<HTMLDivElement | null>;
   pinnedSubagent: {
     toolCallId: string | null;
@@ -47,7 +49,9 @@ interface ChatComposerBarProps {
 export function ChatComposerBar({
   isNative,
   isDetached,
+  useDocumentScroll = false,
   floatingBarRef,
+  footerReserveRef,
   morphRef,
   pinnedSubagent,
   subagentStore,
@@ -75,15 +79,48 @@ export function ChatComposerBar({
 }: ChatComposerBarProps) {
   if (isNative) return null;
 
-  return (
+  const showScrollPill = scrollPhase === "pill";
+  const documentScrollClassName = "pointer-events-none relative z-20 flex justify-center px-3 md:px-6 animate-[fadeIn_400ms_ease-out]";
+  const wrapperClassName = useDocumentScroll
+    ? documentScrollClassName
+    : `pointer-events-none fixed inset-x-0 bottom-0 z-20 flex justify-center px-3 ${isDetached ? "pb-[1.5dvh]" : "pb-[3dvh]"} md:px-6 ${isDetached ? "md:pb-[1.5dvh]" : "md:pb-[3dvh]"} animate-[fadeIn_400ms_ease-out]`;
+  const wrapperStyle = useDocumentScroll
+    ? { paddingBottom: "calc(env(safe-area-inset-bottom, 0px) + 0.75rem)" }
+    : undefined;
+  const scrollPillOffset = useDocumentScroll
+    ? "calc(env(safe-area-inset-bottom, 0px) + 0.75rem)"
+    : isDetached
+      ? "calc(1.5dvh + 4.5rem)"
+      : "calc(3dvh + 4.5rem)";
+  const scrollPillContainerStyle = useDocumentScroll
+    ? { bottom: "calc(env(safe-area-inset-bottom, 0px) + 0.8rem)" }
+    : { paddingBottom: scrollPillOffset };
+  const scrollPill = showScrollPill ? (
+    <div
+      className="pointer-events-none fixed inset-x-0 bottom-0 z-30 flex justify-center px-3 md:px-6 animate-[fadeIn_200ms_ease-out]"
+      style={scrollPillContainerStyle}
+    >
+      <button
+        type="button"
+        onClick={onScrollToBottom}
+        className="pointer-events-auto inline-flex items-center gap-2 rounded-full border border-border bg-background/75 px-4 py-2.5 text-xs font-medium text-foreground shadow-[0_2px_4px_rgba(49,49,49,0.08)] backdrop-blur-[12px] backdrop-saturate-[1.8]"
+      >
+        <span aria-hidden="true" className="text-sm leading-none">↓</span>
+        <span>Scroll to bottom</span>
+      </button>
+    </div>
+  ) : null;
+
+  const renderComposer = (ref: React.RefObject<HTMLDivElement | null>) => (
     <div
-      ref={floatingBarRef}
-      className={`pointer-events-none fixed inset-x-0 bottom-0 z-20 flex justify-center px-3 ${isDetached ? "pb-[1.5dvh]" : "pb-[3dvh]"} md:px-6 ${isDetached ? "md:pb-[1.5dvh]" : "md:pb-[3dvh]"} animate-[fadeIn_400ms_ease-out]`}
+      ref={ref}
+      className={wrapperClassName}
+      style={wrapperStyle}
     >
       <div
         ref={morphRef}
         className="pointer-events-auto w-full"
-        style={{ maxWidth: "min(calc(200px + (100% - 200px) * (1 - var(--lp, 0))), calc(200px + (42rem - 200px) * (1 - var(--lp, 0))))" } as React.CSSProperties}
+        style={{ maxWidth: "42rem" } as React.CSSProperties}
       >
         {pinnedSubagent && (
           <div style={{ paddingLeft: "calc(48px * (1 - var(--lp, 0)))", paddingRight: "calc(48px * (1 - var(--lp, 0)))" } as React.CSSProperties}>
@@ -109,6 +146,7 @@ export function ChatComposerBar({
           onSend={onSend}
           scrollPhase={scrollPhase}
           onScrollToBottom={onScrollToBottom}
+          disableScrollMorph
           availableModels={availableModels}
           modelsLoading={modelsLoading}
           onFetchModels={onFetchModels}
@@ -127,4 +165,20 @@ export function ChatComposerBar({
       </div>
     </div>
   );
+
+  if (!useDocumentScroll) {
+    return (
+      <>
+        {renderComposer(floatingBarRef)}
+        {scrollPill}
+      </>
+    );
+  }
+
+  return (
+    <>
+      {renderComposer(footerReserveRef ?? floatingBarRef)}
+      {scrollPill}
+    </>
+  );
 }
diff --git a/components/chat/ChatViewport.tsx b/components/chat/ChatViewport.tsx
index 4ca2cad..7870340 100644
--- a/components/chat/ChatViewport.tsx
+++ b/components/chat/ChatViewport.tsx
@@ -20,6 +20,7 @@ interface ChatViewportProps {
   isDetached: boolean;
   detachedNoBorder?: boolean;
   isNative: boolean;
+  useDocumentScroll?: boolean;
   historyLoaded: boolean;
   inputZoneHeight: string;
   bottomPad: string;
@@ -56,6 +57,7 @@ export function ChatViewport({
   isDetached,
   detachedNoBorder = false,
   isNative,
+  useDocumentScroll = false,
   historyLoaded,
   inputZoneHeight,
   bottomPad,
@@ -211,6 +213,19 @@ export function ChatViewport({
     return { byIndex, groupIds, multiGroupIds };
   }, [zenDisplayMessages]);
 
+  // Group consecutive tool-only messages so they render in a single tight container
+  const toolGroupMap = useMemo(() => {
+    const isToolOnly = (m: typeof zenDisplayMessages[0]) =>
+      m.role === "assistant" && Array.isArray(m.content) && m.content.length > 0 &&
+      m.content.every((p: any) => isToolCallPart(p) || (p.type === "text" && !p.text?.trim()) || p.type === "thinking");
+    const map = new Map<number, number>(); // idx -> group head idx
+    for (let i = 0; i < zenDisplayMessages.length; i++) {
+      if (!isToolOnly(zenDisplayMessages[i])) continue;
+      map.set(i, i > 0 && map.has(i - 1) ? map.get(i - 1)! : i);
+    }
+    return map;
+  }, [zenDisplayMessages]);
+
   const clearGroupTimers = useCallback((groupId: string) => {
     const timers = animationTimersRef.current[groupId];
     if (!timers) return;
@@ -674,12 +689,15 @@ export function ChatViewport({
   }, [clearModeTimers]);
 
   return (
-    <div ref={pullContentRef} className={`relative flex flex-1 flex-col min-h-0 ${detachedShell ? "px-3 pt-3" : ""}`}>
+    <div
+      ref={pullContentRef}
+      className={`relative flex flex-col ${useDocumentScroll ? "" : "flex-1 min-h-0"} ${detachedShell ? "px-3 pt-3" : ""}`}
+    >
 
-      {!isNative && <div className={`pointer-events-none absolute z-20 h-7 opacity-60 ${detachedShell ? "inset-x-3 rounded-b-2xl" : "inset-x-0"}`} style={{ bottom: isDetached ? inputZoneHeight : 0, background: "linear-gradient(to top, var(--background) 40%, transparent)" }} />}
+      {!isNative && !useDocumentScroll && <div className={`pointer-events-none absolute z-20 h-7 opacity-60 ${detachedShell ? "inset-x-3 rounded-b-2xl" : "inset-x-0"}`} style={{ bottom: isDetached ? inputZoneHeight : 0, background: "linear-gradient(to top, var(--background) 40%, transparent)" }} />}
       <main
         ref={scrollRef}
-        onScroll={() => {
+        onScroll={useDocumentScroll ? undefined : () => {
           onScroll();
           if (onNativeScrollPosition && scrollRef.current) {
             const el = scrollRef.current;
@@ -687,12 +705,13 @@ export function ChatViewport({
             onNativeScrollPosition(distFromBottom);
           }
         }}
-        className={`scrollbar-hide flex-1 overflow-y-auto overflow-x-hidden ${isNative ? "" : "bg-background"} ${detachedShell ? "rounded-2xl" : (!isDetached ? "pt-14" : "")}`}
-        style={{ ...(isNative ? {} : { overscrollBehavior: "none" as const }), ...(detachedShell ? { boxShadow: "0 -4px 6px -1px rgb(0 0 0 / 0.06), 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)" } : {}) }}
+        className={`scrollbar-hide ${useDocumentScroll ? "overflow-visible" : "flex-1 overflow-y-auto overflow-x-hidden"} ${isNative ? "" : "bg-background"} ${detachedShell ? "rounded-2xl" : (!isDetached ? "pt-14" : "")}`}
+        style={{ ...(isNative || useDocumentScroll ? {} : { overscrollBehavior: "none" as const }), ...(detachedShell ? { boxShadow: "0 -4px 6px -1px rgb(0 0 0 / 0.06), 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)" } : {}) }}
       >
         <div className={`mx-auto flex w-full ${isDetached || isNative ? "max-w-none" : "max-w-2xl"} flex-col gap-3 px-4 py-6 md:px-6 md:py-4 transition-opacity duration-300 ease-out ${historyLoaded ? "opacity-100" : "opacity-0"}`} style={{ paddingBottom: bottomPad }}>
           {isNative && <div aria-hidden="true" style={{ height: IOS_TOP_MESSAGE_SPACER_HEIGHT, flexShrink: 0 }} />}
           {zenDisplayMessages.map((msg, idx) => {
+            const toolGroupHead = toolGroupMap.get(idx) ?? -1;
             const side = getMessageSide(msg.role);
             const prevSide = idx > 0 ? getMessageSide(zenDisplayMessages[idx - 1].role) : null;
             const prevTimestamp = idx > 0 ? zenDisplayMessages[idx - 1].timestamp : null;
@@ -810,31 +829,41 @@ export function ChatViewport({
                     />
                   </div>
                 )}
-                <div
-                  style={messageRowWrapperStyle}
-                  onAnimationEnd={!isZenSiblingRow && msg.id === sentAnimId && !isSentUserAnim ? onSentAnimationEnd : undefined}
-                >
-                  <MessageRow
-                    message={msg}
-                    isStreaming={isStreaming && msg.id === effectiveStreamingId}
-                    freezeStreamingLayout={freezeStreamingLayout}
-                    subagentStore={subagentStore}
-                    pinnedToolCallId={pinnedToolCallId}
-                    onPin={onPin}
-                    onUnpin={onUnpin}
-                    zenMode={zenRenderMode}
-                    zenGroupCollapsible={false}
-                    zenGroupExpanded={zenGroupExpanded}
-                    zenCollapsedByGroup={isZenSiblingRow}
-                    zenGroupSlideOpen={effectiveRowSlideOpen}
-                    zenGroupFadeVisible={effectiveRowFadeVisible}
-                    onZenGroupToggle={undefined}
-                    isSentAnim={isSentUserAnim}
-                    onSentAnimationEnd={isSentUserAnim ? onSentAnimationEnd : undefined}
-                    onPluginAction={onPluginAction}
-                    onAddInputAttachment={onAddInputAttachment}
-                  />
-                </div>
+                {toolGroupHead >= 0 && toolGroupHead !== idx ? null : (
+                  <div
+                    style={messageRowWrapperStyle}
+                    onAnimationEnd={!isZenSiblingRow && msg.id === sentAnimId && !isSentUserAnim ? onSentAnimationEnd : undefined}
+                  >
+                    <MessageRow
+                      message={toolGroupHead === idx ? (() => {
+                        // Merge all tool-only messages in this group into one
+                        const parts: any[] = [];
+                        for (let gi = idx; toolGroupMap.get(gi) === idx; gi++) {
+                          const gMsg = zenDisplayMessages[gi];
+                          if (Array.isArray(gMsg.content)) parts.push(...gMsg.content);
+                        }
+                        return { ...msg, content: parts };
+                      })() : msg}
+                      isStreaming={isStreaming && msg.id === effectiveStreamingId}
+                      freezeStreamingLayout={freezeStreamingLayout}
+                      subagentStore={subagentStore}
+                      pinnedToolCallId={pinnedToolCallId}
+                      onPin={onPin}
+                      onUnpin={onUnpin}
+                      zenMode={zenRenderMode}
+                      zenGroupCollapsible={false}
+                      zenGroupExpanded={zenGroupExpanded}
+                      zenCollapsedByGroup={isZenSiblingRow}
+                      zenGroupSlideOpen={effectiveRowSlideOpen}
+                      zenGroupFadeVisible={effectiveRowFadeVisible}
+                      onZenGroupToggle={undefined}
+                      isSentAnim={isSentUserAnim}
+                      onSentAnimationEnd={isSentUserAnim ? onSentAnimationEnd : undefined}
+                      onPluginAction={onPluginAction}
+                      onAddInputAttachment={onAddInputAttachment}
+                    />
+                  </div>
+                )}
               </React.Fragment>
             );
           })}
@@ -842,7 +871,7 @@ export function ChatViewport({
         </div>
       </main>
 
-      {isDetached && !isNative && <div style={{ height: inputZoneHeight, flexShrink: 0 }} />}
+      {isDetached && !isNative && !useDocumentScroll && <div style={{ height: inputZoneHeight, flexShrink: 0 }} />}
 
       {!isDetached && !isNative && (
         <div
diff --git a/dev-notes/2026-03-25_ios-safari-detached-document-scroll-chat.md b/dev-notes/2026-03-25_ios-safari-detached-document-scroll-chat.md
new file mode 100644
index 0000000..f5dcf52
--- /dev/null
+++ b/dev-notes/2026-03-25_ios-safari-detached-document-scroll-chat.md
@@ -0,0 +1,71 @@
+# iOS Safari Detached Chat Uses Document Scroll
+
+## Goal
+
+Make detached mobile web chat behave like a normal body-scrolling page on iPhone Safari:
+
+- content can extend under Safari chrome
+- the bottom chrome stays visually hidden in the idle state
+- the chat input no longer uses the old morphing/fixed-shell behavior
+
+## What Finally Worked
+
+Detached mobile web now switches to a document-scroll mode instead of the old `100dvh` locked shell.
+
+Key pieces:
+
+1. `app/page.tsx` enables `useDocumentScroll` only for detached, non-native, mobile-width chat.
+2. `html` / `body` scrolling is unlocked for that mode.
+3. `ChatViewport` stops owning `overflow-y-auto` in that mode and becomes normal document content.
+4. The composer stays in normal flow instead of switching to `fixed` on focus.
+5. The old textarea ↔ scroll-pill morph is disabled; the jump affordance is now a separate floating control.
+
+## Important Safari Findings
+
+### 1. Bottom-pinned controls wake the Safari chrome back up
+
+Any fixed control too close to the bottom edge caused Safari's bottom chrome to reappear.
+
+The separate `Scroll to bottom` pill only stayed compatible once it was moved up to:
+
+```css
+bottom: calc(env(safe-area-inset-bottom, 0px) + 0.8rem)
+```
+
+This was found empirically. Lower values eventually re-triggered the bottom chrome.
+
+### 2. A focused bottom input is not a good experiment primitive
+
+Replacing the jump pill with a real text input showed that Safari auto-pans the document to accommodate focused text fields. Near the page bottom this can hit the document end, snap, and collapse the interaction. So the jump control should stay a button-like control, not a text field.
+
+### 3. The first tap during momentum is Safari behavior
+
+While momentum scrolling is active, the first tap on a floating control often only cancels inertia. This also happens with other floating utilities on the page. Multiple event-handler workarounds did not change that reliably, so the current implementation accepts it as a platform limitation.
+
+### 4. The old focus/resize restore logic became actively harmful
+
+Once document scroll owned the page, the previous `visualViewport.resize` / `focusout` restore hook started snapping the page back to bottom after normal Safari chrome transitions. That hook was removed.
+
+## Current Stable Shape
+
+- detached mobile web: document scroll
+- composer: static, in-flow, no morph
+- jump pill: separate fixed control above the bottom edge
+- desktop / native / non-detached paths: existing behavior preserved
+
+## Files
+
+- `app/page.tsx`
+- `components/ChatInput.tsx`
+- `components/chat/ChatComposerBar.tsx`
+- `components/chat/ChatViewport.tsx`
+- `hooks/useScrollManager.ts`
+- `lib/chat/layout.ts`
+
+## Known Limitation
+
+On iOS Safari, tapping the floating jump pill during active momentum scroll may require a second tap because the first tap is consumed by inertia cancellation. This appears to be browser behavior rather than a chat-specific bug.
+
+## Follow-Up
+
+- BUG: Scrolling in detached mode on desktop no longer works.
diff --git a/hooks/chat/useOpenClawRuntime.ts b/hooks/chat/useOpenClawRuntime.ts
index 9127481..a11cf8b 100644
--- a/hooks/chat/useOpenClawRuntime.ts
+++ b/hooks/chat/useOpenClawRuntime.ts
@@ -52,6 +52,7 @@ interface StreamActions {
 interface UseOpenClawRuntimeOptions extends StreamActions {
   backendMode: BackendMode;
   isNative: boolean;
+  useDocumentScroll?: boolean;
   isDetachedRef: React.MutableRefObject<boolean>;
   isNativeRef: React.MutableRefObject<boolean>;
   scrollRef: React.RefObject<HTMLDivElement | null>;
@@ -109,6 +110,7 @@ const SLEEP_GAP_CHECK_MS = 15_000;
 export function useOpenClawRuntime({
   backendMode,
   isNative,
+  useDocumentScroll = false,
   isDetachedRef,
   isNativeRef,
   scrollRef,
@@ -211,7 +213,7 @@ export function useOpenClawRuntime({
     backendMode,
     sendWS,
     sessionKeyRef,
-    enabled: !isNative,
+    enabled: !isNative && !useDocumentScroll,
   });
 
   const requestHistory = useCallback(() => {
@@ -532,6 +534,13 @@ export function useOpenClawRuntime({
         break;
       }
 
+      case "retrying":
+        // Server is retrying after a rate-limit error — drop the partial
+        // assistant message so the fresh stream creates a clean one.
+        setMessages((prev) => prev.filter((m) => m.id !== payload.runId));
+        clearThinkingSource(payload.runId);
+        break;
+
       case "error": {
         if (activeRunIdRef.current && payload.runId && payload.runId !== activeRunIdRef.current) {
           if (!queuedMessageRef.current) requestHistory();
@@ -872,6 +881,14 @@ export function useOpenClawRuntime({
       return;
     }
 
+    // Skip history refetch during an active run — the WS is already
+    // delivering realtime events, and refetching would clobber streaming
+    // state (e.g. plugin cards mounted during the run).
+    if (activeRunIdRef.current) {
+      console.log(`[WS] Resume sync (${reason}) skipped — run in progress`);
+      return;
+    }
+
     const sent = requestHistory();
     if (!sent) {
       console.log(`[WS] Resume sync (${reason}) history request failed -> reconnect`);
diff --git a/hooks/useAppMode.ts b/hooks/useAppMode.ts
index 8c04d18..b4a8b18 100644
--- a/hooks/useAppMode.ts
+++ b/hooks/useAppMode.ts
@@ -73,7 +73,7 @@ export function useAppMode(): AppMode {
     isDetachedRef.current = resolvedMode.isDetached;
     isNativeRef.current = resolvedMode.isNative;
 
-    const shouldUseTransparentHostBackground = widgetCtx?.transparentHostBackground !== false
+    const shouldUseTransparentHostBackground = widgetCtx ? widgetCtx.transparentHostBackground !== false : false;
 
     if (resolvedMode.isDetached && shouldUseTransparentHostBackground) {
       document.body.style.background = "transparent";
diff --git a/hooks/useIsMobileViewport.ts b/hooks/useIsMobileViewport.ts
new file mode 100644
index 0000000..a1910c2
--- /dev/null
+++ b/hooks/useIsMobileViewport.ts
@@ -0,0 +1,25 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+const MOBILE_VIEWPORT_QUERY = "(max-width: 767px)";
+
+export function useIsMobileViewport() {
+  const [isMobileViewport, setIsMobileViewport] = useState(() => {
+    if (typeof window === "undefined") return false;
+    return window.matchMedia(MOBILE_VIEWPORT_QUERY).matches;
+  });
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+
+    const media = window.matchMedia(MOBILE_VIEWPORT_QUERY);
+    const update = () => setIsMobileViewport(media.matches);
+
+    update();
+    media.addEventListener("change", update);
+    return () => media.removeEventListener("change", update);
+  }, []);
+
+  return isMobileViewport;
+}
diff --git a/hooks/useScrollManager.ts b/hooks/useScrollManager.ts
index 730010e..0e2ec6f 100644
--- a/hooks/useScrollManager.ts
+++ b/hooks/useScrollManager.ts
@@ -13,14 +13,21 @@ const STREAM_REPIN_DISTANCE_PX = 32;
  * Manages scroll tracking, auto-scroll pinning, morph bar animation,
  * and ResizeObserver-based content tracking.
  */
-export function useScrollManager(
-  messages: Message[],
-  isStreamingRef: React.RefObject<boolean>,
-  isNativeRef?: React.RefObject<boolean>,
-) {
+export function useScrollManager({
+  messages,
+  isStreamingRef,
+  isNativeRef,
+  useDocumentScroll = false,
+}: {
+  messages: Message[];
+  isStreamingRef: React.RefObject<boolean>;
+  isNativeRef?: React.RefObject<boolean>;
+  useDocumentScroll?: boolean;
+}) {
   const [scrollPhase, setScrollPhase] = useState<"input" | "pill">("input");
   const scrollRef = useRef<HTMLDivElement>(null);
   const bottomRef = useRef<HTMLDivElement>(null);
+  const footerReserveRef = useRef<HTMLDivElement>(null);
   const morphRef = useRef<HTMLDivElement>(null);
   const scrollRafId = useRef<number | null>(null);
   const scrollPhaseRef = useRef<"input" | "pill">("input");
@@ -50,6 +57,44 @@ export function useScrollManager(
   const manualStreamUnpinRef = useRef(false);
   const wheelUpIntentRef = useRef(0);
 
+  const getScrollElement = useCallback(() => {
+    if (typeof document === "undefined") return null;
+    return (useDocumentScroll ? (document.scrollingElement ?? document.documentElement) : scrollRef.current) as HTMLElement | null;
+  }, [useDocumentScroll]);
+
+  const getViewportHeight = useCallback((el: HTMLElement | null) => {
+    if (!el) return 0;
+    return el.clientHeight;
+  }, []);
+
+  const getDocumentChromeOffset = useCallback(() => {
+    if (!useDocumentScroll || typeof document === "undefined" || typeof window === "undefined") return 0;
+    const probe = document.createElement("div");
+    probe.style.cssText = "position:fixed;left:-9999px;top:0;height:100vh;width:0;pointer-events:none;";
+    document.body.appendChild(probe);
+    const layoutViewportHeight = probe.getBoundingClientRect().height;
+    probe.remove();
+    return Math.max(0, layoutViewportHeight - window.innerHeight);
+  }, [useDocumentScroll]);
+
+  const getDocumentBottomTarget = useCallback((el: HTMLElement | null) => {
+    if (!el || !useDocumentScroll || !bottomRef.current) return null;
+    const footerReserveHeight = footerReserveRef.current?.getBoundingClientRect().height ?? 0;
+    const viewportHeight = getViewportHeight(el);
+    const bottomTop = bottomRef.current.getBoundingClientRect().top + el.scrollTop;
+    const chromeOffset = getDocumentChromeOffset();
+    return Math.max(0, bottomTop - (viewportHeight - footerReserveHeight) + chromeOffset);
+  }, [getDocumentChromeOffset, getViewportHeight, useDocumentScroll]);
+
+  const getDistanceFromBottom = useCallback((el: HTMLElement | null) => {
+    if (!el) return 0;
+    const documentTarget = getDocumentBottomTarget(el);
+    if (documentTarget != null) {
+      return Math.max(0, documentTarget - el.scrollTop);
+    }
+    return el.scrollHeight - el.scrollTop - getViewportHeight(el);
+  }, [getDocumentBottomTarget, getViewportHeight]);
+
   const clearManualStreamUnpin = useCallback(() => {
     manualStreamUnpinRef.current = false;
     wheelUpIntentRef.current = 0;
@@ -149,7 +194,7 @@ export function useScrollManager(
     if (scrollRafId.current != null) return;
     scrollRafId.current = requestAnimationFrame(() => {
       scrollRafId.current = null;
-      const el = scrollRef.current;
+      const el = getScrollElement();
       if (!el) return;
 
       // Detect container resize (keyboard open/close, viewport change).
@@ -159,12 +204,14 @@ export function useScrollManager(
       // the morph locked at 0 so the input bar doesn't glitch.
       // (Third-party keyboards like SwiftKey resize in multiple discrete steps,
       // so this can fire several times during a single keyboard animation.)
-      const currentHeight = el.clientHeight;
+      const currentHeight = getViewportHeight(el);
       const heightChanged = Math.abs(currentHeight - lastClientHeightRef.current) > 2;
       lastClientHeightRef.current = currentHeight;
 
       if (heightChanged && pinnedToBottomRef.current) {
-        el.scrollTop = el.scrollHeight;
+        if (!useDocumentScroll) {
+          el.scrollTop = el.scrollHeight;
+        }
         setMorphTarget(0);
         return;
       }
@@ -176,7 +223,7 @@ export function useScrollManager(
         return;
       }
 
-      const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
+      const distanceFromBottom = getDistanceFromBottom(el);
 
       // During streaming or pin-lock window, don't unpin from scroll position —
       // only the wheel/touch handlers can unpin. But DO allow re-pinning when
@@ -200,7 +247,7 @@ export function useScrollManager(
       const progress = Math.min(Math.max(distanceFromBottom / range, 0), 1);
       setMorphTarget(progress);
     });
-  }, [clearManualStreamUnpin, isStreamingRef, setMorphTarget]);
+  }, [clearManualStreamUnpin, getDistanceFromBottom, getScrollElement, getViewportHeight, isStreamingRef, setMorphTarget, useDocumentScroll]);
 
   /** Clear any stuck bounce transform on the content div. */
   const clearBounceTransform = useCallback(() => {
@@ -216,15 +263,15 @@ export function useScrollManager(
   // Flag to prevent ResizeObserver from snapping scrollTop mid-animation
   const isAnimatingScrollRef = useRef(false);
 
-  const scrollToBottom = useCallback(() => {
+  const scrollToBottom = useCallback((opts?: { instant?: boolean }) => {
     pinnedToBottomRef.current = true;
     pinLockUntilRef.current = Date.now() + PIN_LOCK_MS;
     clearManualStreamUnpin();
     clearBounceTransform();
-    const el = scrollRef.current;
+    const el = getScrollElement();
     if (!el) return;
 
-    const target = el.scrollHeight - el.clientHeight;
+    const target = getDocumentBottomTarget(el) ?? (el.scrollHeight - getViewportHeight(el));
     const start = el.scrollTop;
     const distance = target - start;
     if (distance <= 0) {
@@ -233,6 +280,12 @@ export function useScrollManager(
       return;
     }
 
+    if (opts?.instant) {
+      el.scrollTop = target;
+      setMorphTarget(0);
+      return;
+    }
+
     // During streaming/grace the rAF loop pins us to bottom every frame,
     // so just snap — a smooth animation would be overridden anyway.
     if (isStreamingRef.current || scrollGraceRef.current) {
@@ -266,27 +319,28 @@ export function useScrollManager(
     };
 
     requestAnimationFrame(animate);
-  }, [clearBounceTransform, clearManualStreamUnpin, isStreamingRef, setMorphTarget]);
+  }, [clearBounceTransform, clearManualStreamUnpin, getDocumentBottomTarget, getScrollElement, getViewportHeight, isStreamingRef, setMorphTarget]);
 
   // Auto-scroll: whenever messages change, snap to bottom if pinned.
   // During streaming, the rAF loop handles smooth scrolling instead.
   useLayoutEffect(() => {
     if (!pinnedToBottomRef.current || messages.length === 0) return;
     if (isStreamingRef.current) return;
-    const el = scrollRef.current;
+    const el = getScrollElement();
     if (!el) return;
     if (!hasScrolledInitialRef.current) {
       hasScrolledInitialRef.current = true;
     }
     clearBounceTransform();
-    el.scrollTop = el.scrollHeight;
-  }, [messages, clearBounceTransform]);
+    el.scrollTop = getDocumentBottomTarget(el) ?? el.scrollHeight;
+  }, [messages, clearBounceTransform, getDocumentBottomTarget, getScrollElement]);
 
   // ResizeObserver: catch content-height changes (e.g. images loading, zen collapses).
   useEffect(() => {
-    const el = scrollRef.current;
-    if (!el) return;
-    const content = el.firstElementChild as HTMLElement | null;
+    const el = getScrollElement();
+    const surface = scrollRef.current;
+    if (!el || !surface) return;
+    const content = surface.firstElementChild as HTMLElement | null;
     if (!content) return;
 
     const ro = new ResizeObserver(() => {
@@ -311,17 +365,17 @@ export function useScrollManager(
         content.style.minHeight = "";
       }
 
-      if ((pinnedToBottomRef.current || scrollGraceRef.current) && el.scrollHeight > el.clientHeight) {
+      if ((pinnedToBottomRef.current || scrollGraceRef.current) && el.scrollHeight > getViewportHeight(el)) {
         // During grace period the rAF momentum loop is still running —
         // let it smoothly catch up instead of hard-snapping.
         if (!scrollGraceRef.current) {
-          el.scrollTop = el.scrollHeight;
+          el.scrollTop = getDocumentBottomTarget(el) ?? el.scrollHeight;
         }
         pinnedToBottomRef.current = true;
       } else if (!pinnedToBottomRef.current && !scrollGraceRef.current) {
         // Content shrank (e.g. collapsing a tool call) while unpinned.
         // If we're now back at the bottom, re-pin and clear the pill.
-        const dist = el.scrollHeight - el.scrollTop - el.clientHeight;
+        const dist = getDistanceFromBottom(el);
         if (dist < 80) {
           pinnedToBottomRef.current = true;
           setMorphTarget(Math.min(Math.max(dist / 60, 0), 1));
@@ -330,14 +384,14 @@ export function useScrollManager(
     });
     ro.observe(content);
     return () => ro.disconnect();
-  }, [setMorphTarget]);
+  }, [getDistanceFromBottom, getDocumentBottomTarget, getScrollElement, getViewportHeight, setMorphTarget]);
 
   // rAF loop: during streaming, smoothly scroll toward bottom.
   // Uses velocity with momentum — desired speed scales with gap size,
   // actual velocity smoothly blends toward desired. No stutters on retarget.
   // All constants are normalized to 60fps so behavior is consistent at any refresh rate.
   useEffect(() => {
-    const el = scrollRef.current;
+    const el = getScrollElement();
     if (!el) return;
     let id: number;
     // velocity in px-per-60fps-frame; multiplied by frameScale before applying
@@ -377,9 +431,9 @@ export function useScrollManager(
       if (
         (pinnedToBottomRef.current || scrollGraceRef.current) &&
         (isStreamingRef.current || scrollGraceRef.current) &&
-        el.scrollHeight > el.clientHeight
+        el.scrollHeight > getViewportHeight(el)
       ) {
-        const target = el.scrollHeight - el.clientHeight;
+        const target = getDocumentBottomTarget(el) ?? (el.scrollHeight - getViewportHeight(el));
         const diff = target - el.scrollTop;
 
         if (diff > SCROLL_MIN_DIFF) {
@@ -408,19 +462,22 @@ export function useScrollManager(
     };
     id = requestAnimationFrame(tick);
     return () => cancelAnimationFrame(id);
-  }, []);
+  }, [getDocumentBottomTarget, getScrollElement, getViewportHeight, isStreamingRef]);
 
   // Unpin auto-scroll when user actively scrolls up (wheel or touch).
   useEffect(() => {
-    const el = scrollRef.current;
-    if (!el) return;
+    const el = getScrollElement();
+    const eventTarget: Window | HTMLElement | null = useDocumentScroll ? window : scrollRef.current;
+    if (!el || !eventTarget) return;
 
     let touchStartY = 0;
 
-    const onTouchStart = (e: TouchEvent) => {
+    const onTouchStart = (event: Event) => {
+      const e = event as TouchEvent;
       touchStartY = e.touches[0].clientY;
     };
-    const onTouchMove = (e: TouchEvent) => {
+    const onTouchMove = (event: Event) => {
+      const e = event as TouchEvent;
       if (isStreamingRef.current && pinnedToBottomRef.current) {
         const dy = e.touches[0].clientY - touchStartY;
         if (dy > STREAM_TOUCH_UNPIN_DELTA_PX) {
@@ -430,15 +487,16 @@ export function useScrollManager(
     };
     const onTouchEnd = () => {
       if (isStreamingRef.current && !manualStreamUnpinRef.current) {
-        const dist = el.scrollHeight - el.scrollTop - el.clientHeight;
+        const dist = getDistanceFromBottom(getScrollElement());
         if (dist < 80) pinnedToBottomRef.current = true;
       }
     };
-    const onWheel = (e: WheelEvent) => {
+    const onWheel = (event: Event) => {
+      const e = event as WheelEvent;
       if (isStreamingRef.current && pinnedToBottomRef.current) {
         if (e.deltaY < 0) {
           wheelUpIntentRef.current += Math.abs(e.deltaY);
-          const dist = el.scrollHeight - el.scrollTop - el.clientHeight;
+          const dist = getDistanceFromBottom(getScrollElement());
           if (dist > STREAM_UNPIN_DISTANCE_PX || wheelUpIntentRef.current >= STREAM_WHEEL_UNPIN_DELTA_PX) {
             disengageStreamingAutoscroll();
           }
@@ -449,17 +507,19 @@ export function useScrollManager(
     };
     let lastScrollTop = el.scrollTop;
     const onScroll = () => {
-      const currentScrollTop = el.scrollTop;
+      const metricsEl = getScrollElement();
+      if (!metricsEl) return;
+      const currentScrollTop = metricsEl.scrollTop;
       // Unpin during streaming if user scrolls up
       if (isStreamingRef.current && currentScrollTop < lastScrollTop - 3) {
-        const dist = el.scrollHeight - currentScrollTop - el.clientHeight;
+        const dist = getDistanceFromBottom(metricsEl);
         if (dist > STREAM_UNPIN_DISTANCE_PX) {
           disengageStreamingAutoscroll();
         }
       }
       // Re-pin during streaming/grace if user scrolls near bottom
       if ((isStreamingRef.current || scrollGraceRef.current) && !pinnedToBottomRef.current) {
-        const dist = el.scrollHeight - currentScrollTop - el.clientHeight;
+        const dist = getDistanceFromBottom(metricsEl);
         const scrollingDown = currentScrollTop > lastScrollTop + 1;
         const canRepin = !manualStreamUnpinRef.current
           ? dist < 80
@@ -473,25 +533,33 @@ export function useScrollManager(
       lastScrollTop = currentScrollTop;
     };
 
-    el.addEventListener("touchstart", onTouchStart, { passive: true });
-    el.addEventListener("touchmove", onTouchMove, { passive: true });
-    el.addEventListener("touchend", onTouchEnd, { passive: true });
-    el.addEventListener("touchcancel", onTouchEnd, { passive: true });
-    el.addEventListener("wheel", onWheel, { passive: true });
-    el.addEventListener("scroll", onScroll, { passive: true });
+    eventTarget.addEventListener("touchstart", onTouchStart, { passive: true });
+    eventTarget.addEventListener("touchmove", onTouchMove, { passive: true });
+    eventTarget.addEventListener("touchend", onTouchEnd, { passive: true });
+    eventTarget.addEventListener("touchcancel", onTouchEnd, { passive: true });
+    eventTarget.addEventListener("wheel", onWheel, { passive: true });
+    eventTarget.addEventListener("scroll", onScroll, { passive: true });
     return () => {
-      el.removeEventListener("touchstart", onTouchStart);
-      el.removeEventListener("touchmove", onTouchMove);
-      el.removeEventListener("touchend", onTouchEnd);
-      el.removeEventListener("touchcancel", onTouchEnd);
-      el.removeEventListener("wheel", onWheel);
-      el.removeEventListener("scroll", onScroll);
+      eventTarget.removeEventListener("touchstart", onTouchStart);
+      eventTarget.removeEventListener("touchmove", onTouchMove);
+      eventTarget.removeEventListener("touchend", onTouchEnd);
+      eventTarget.removeEventListener("touchcancel", onTouchEnd);
+      eventTarget.removeEventListener("wheel", onWheel);
+      eventTarget.removeEventListener("scroll", onScroll);
     };
-  }, [clearManualStreamUnpin, disengageStreamingAutoscroll, isNativeRef, isStreamingRef]);
+  }, [clearManualStreamUnpin, disengageStreamingAutoscroll, getDistanceFromBottom, getScrollElement, isNativeRef, isStreamingRef, useDocumentScroll]);
+
+  useEffect(() => {
+    if (!useDocumentScroll) return;
+    const onWindowScroll = () => handleScroll();
+    window.addEventListener("scroll", onWindowScroll, { passive: true });
+    return () => window.removeEventListener("scroll", onWindowScroll);
+  }, [handleScroll, useDocumentScroll]);
 
   return {
     scrollRef,
     bottomRef,
+    footerReserveRef,
     morphRef,
     scrollPhase,
     pinnedToBottomRef,
diff --git a/lib/chat/layout.ts b/lib/chat/layout.ts
index d6d7c8e..92eb3d6 100644
--- a/lib/chat/layout.ts
+++ b/lib/chat/layout.ts
@@ -6,6 +6,10 @@ const BOTTOM_PAD_DETACHED_BASE = "4rem";
 const BOTTOM_PAD_DETACHED_QUEUED = "7rem";
 const BOTTOM_PAD_DETACHED_PINNED = "10rem";
 const BOTTOM_PAD_NATIVE = "8rem";
+const BOTTOM_PAD_DOCUMENT_SCROLL = "calc(env(safe-area-inset-bottom, 0px) + 1.5rem)";
+const FOOTER_RESERVE_DOCUMENT_SCROLL_BASE = "calc(env(safe-area-inset-bottom, 0px) + 4rem)";
+const FOOTER_RESERVE_DOCUMENT_SCROLL_QUEUED = "calc(env(safe-area-inset-bottom, 0px) + 7rem)";
+const FOOTER_RESERVE_DOCUMENT_SCROLL_PINNED = "calc(env(safe-area-inset-bottom, 0px) + 10rem)";
 const THINKING_INDICATOR_GAP = "1.5rem";
 
 export const DEFAULT_INPUT_ZONE_HEIGHT = "calc(1.5dvh + 3.5rem)";
@@ -17,17 +21,20 @@ function addCalc(...parts: string[]): string {
 export function getChatBottomPad({
   isNative,
   isDetached,
+  useDocumentScroll = false,
   inputZoneHeight = DEFAULT_INPUT_ZONE_HEIGHT,
   hasQueued,
   hasPinnedSubagent,
 }: {
   isNative: boolean;
   isDetached: boolean;
+  useDocumentScroll?: boolean;
   inputZoneHeight?: string;
   hasQueued: boolean;
   hasPinnedSubagent: boolean;
 }): string {
   if (isNative) return BOTTOM_PAD_NATIVE;
+  if (useDocumentScroll) return BOTTOM_PAD_DOCUMENT_SCROLL;
 
   if (isDetached) {
     const overlayPad = hasPinnedSubagent
@@ -49,12 +56,29 @@ export function getChatBottomPad({
 
 export function getThinkingIndicatorBottom({
   isDetached,
+  useDocumentScroll = false,
   inputZoneHeight = DEFAULT_INPUT_ZONE_HEIGHT,
 }: {
   isDetached: boolean;
+  useDocumentScroll?: boolean;
   inputZoneHeight?: string;
 }): string {
+  if (useDocumentScroll) {
+    return addCalc(BOTTOM_PAD_DOCUMENT_SCROLL, THINKING_INDICATOR_GAP);
+  }
   return isDetached
     ? addCalc(inputZoneHeight, inputZoneHeight, THINKING_INDICATOR_GAP)
     : addCalc(inputZoneHeight, THINKING_INDICATOR_GAP);
 }
+
+export function getDocumentScrollFooterReserve({
+  hasQueued,
+  hasPinnedSubagent,
+}: {
+  hasQueued: boolean;
+  hasPinnedSubagent: boolean;
+}): string {
+  if (hasPinnedSubagent) return FOOTER_RESERVE_DOCUMENT_SCROLL_PINNED;
+  if (hasQueued) return FOOTER_RESERVE_DOCUMENT_SCROLL_QUEUED;
+  return FOOTER_RESERVE_DOCUMENT_SCROLL_BASE;
+}
diff --git a/tests/layout.test.ts b/tests/layout.test.ts
index 824d5f7..fe16469 100644
--- a/tests/layout.test.ts
+++ b/tests/layout.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { getChatBottomPad, getThinkingIndicatorBottom } from "@mc/lib/chat/layout";
+import { getChatBottomPad, getDocumentScrollFooterReserve, getThinkingIndicatorBottom } from "@mc/lib/chat/layout";
 
 describe("chat layout spacing", () => {
   it("adds composer clearance to detached bottom padding", () => {
@@ -30,10 +30,46 @@ describe("chat layout spacing", () => {
     })).toBe("calc(4rem + 4rem + 1.5rem)");
   });
 
+  it("uses a small bottom inset when document scroll owns the page", () => {
+    expect(getChatBottomPad({
+      isNative: false,
+      isDetached: true,
+      useDocumentScroll: true,
+      inputZoneHeight: "4rem",
+      hasQueued: true,
+      hasPinnedSubagent: true,
+    })).toBe("calc(env(safe-area-inset-bottom, 0px) + 1.5rem)");
+  });
+
   it("keeps the fullscreen thinking indicator one composer-height above the bottom", () => {
     expect(getThinkingIndicatorBottom({
       isDetached: false,
       inputZoneHeight: "4rem",
     })).toBe("calc(4rem + 1.5rem)");
   });
+
+  it("anchors the thinking indicator above the sticky composer in document scroll mode", () => {
+    expect(getThinkingIndicatorBottom({
+      isDetached: true,
+      useDocumentScroll: true,
+      inputZoneHeight: "4rem",
+    })).toBe("calc(calc(env(safe-area-inset-bottom, 0px) + 1.5rem) + 1.5rem)");
+  });
+
+  it("reserves real document space for the fixed mobile composer stack", () => {
+    expect(getDocumentScrollFooterReserve({
+      hasQueued: false,
+      hasPinnedSubagent: false,
+    })).toBe("calc(env(safe-area-inset-bottom, 0px) + 4rem)");
+
+    expect(getDocumentScrollFooterReserve({
+      hasQueued: true,
+      hasPinnedSubagent: false,
+    })).toBe("calc(env(safe-area-inset-bottom, 0px) + 7rem)");
+
+    expect(getDocumentScrollFooterReserve({
+      hasQueued: false,
+      hasPinnedSubagent: true,
+    })).toBe("calc(env(safe-area-inset-bottom, 0px) + 10rem)");
+  });
 });

From f0625e868d5c23c5aff5f45c239ab67b274c9797 Mon Sep 17 00:00:00 2001
From: Krzysztof Wende <wende@hey.com>
Date: Wed, 25 Mar 2026 15:02:24 +0100
Subject: [PATCH 3/4] Address PR review: scroll morph gating and IPv4
 validation

---
 app/layout.tsx                      | 2 +-
 components/chat/ChatComposerBar.tsx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/app/layout.tsx b/app/layout.tsx
index d9a9301..eec0ce5 100644
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -37,7 +37,7 @@ const headScript = `
   var detached = params.has('detached');
   var detachedMode = detached ? params.get('mode') : null;
   var host = location.hostname;
-  var isIpV4 = /^\\d+\\.\\d+\\.\\d+\\.\\d+$/.test(host);
+  var isIpV4 = /^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/.test(host);
   var isLocalHost = host === 'localhost' || host === '127.0.0.1' || host === '0.0.0.0' || host.endsWith('.local');
   var isPrivateLanIp = /^10\\./.test(host) || /^192\\.168\\./.test(host) || /^172\\.(1[6-9]|2\\d|3[0-1])\\./.test(host);
   var shouldDisableServiceWorker = isDev || isLocalHost || (isIpV4 && isPrivateLanIp);
diff --git a/components/chat/ChatComposerBar.tsx b/components/chat/ChatComposerBar.tsx
index 8cd9581..d400830 100644
--- a/components/chat/ChatComposerBar.tsx
+++ b/components/chat/ChatComposerBar.tsx
@@ -146,7 +146,7 @@ export function ChatComposerBar({
           onSend={onSend}
           scrollPhase={scrollPhase}
           onScrollToBottom={onScrollToBottom}
-          disableScrollMorph
+          disableScrollMorph={useDocumentScroll}
           availableModels={availableModels}
           modelsLoading={modelsLoading}
           onFetchModels={onFetchModels}

From 69ef885e8ae525df23fc9a83e6b6f7d4b4058cc1 Mon Sep 17 00:00:00 2001
From: Krzysztof Wende <wende@hey.com>
Date: Wed, 25 Mar 2026 15:36:26 +0100
Subject: [PATCH 4/4] Polish detached chat shell behavior

---
 app/page.tsx                                  | 20 +++--
 components/chat/ChatComposerBar.tsx           |  9 ++-
 components/chat/ChatViewport.tsx              |  6 +-
 ...os-safari-detached-document-scroll-chat.md |  8 +-
 hooks/useAppMode.ts                           |  4 +
 lib/chat/layoutMode.ts                        | 41 +++++++++++
 tests/layoutMode.test.ts                      | 73 +++++++++++++++++++
 7 files changed, 149 insertions(+), 12 deletions(-)
 create mode 100644 lib/chat/layoutMode.ts
 create mode 100644 tests/layoutMode.test.ts

diff --git a/app/page.tsx b/app/page.tsx
index 227fd59..14652f1 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -26,6 +26,7 @@ import {
 import { buildDisplayMessages } from "@mc/lib/chat/messageTransforms";
 import { applyNativeZenMode } from "@mc/lib/chat/zenBridge";
 import { DEFAULT_INPUT_ZONE_HEIGHT, getChatBottomPad } from "@mc/lib/chat/layout";
+import { getChatLayoutConfig } from "@mc/lib/chat/layoutMode";
 
 import type {
   BackendMode,
@@ -77,9 +78,18 @@ export default forwardRef<ChatInputHandle>(function Home(_props, forwardedRef) {
   const isStreamingRef = useRef(false);
   const [streamingId, setStreamingId] = useState<string | null>(null);
   const [sentAnimId, setSentAnimId] = useState<string | null>(null);
-  const { isDetached, detachedNoBorder, isNative, uploadDisabled, hideChrome, isDetachedRef, isNativeRef } = useAppMode();
+  const { isDetached, detachedNoBorder, detachedSurface, isNative, uploadDisabled, hideChrome, isDetachedRef, isNativeRef } = useAppMode();
   const isMobileViewport = useIsMobileViewport();
-  const useDocumentScroll = isDetached && !isNative && isMobileViewport;
+  const {
+    useDocumentScroll,
+    shellHeight,
+    useKeyboardLayout: shouldUseKeyboardLayout,
+  } = getChatLayoutConfig({
+    isDetached,
+    isNative,
+    isMobileViewport,
+    detachedSurface,
+  });
 
   useEffect(() => {
     if (!useDocumentScroll) return;
@@ -287,7 +297,7 @@ export default forwardRef<ChatInputHandle>(function Home(_props, forwardedRef) {
     setTurnstileChecked(true);
   }, []);
 
-  useKeyboardLayout(appRef, floatingBarRef, bottomRef, !isNative && !useDocumentScroll);
+  useKeyboardLayout(appRef, floatingBarRef, bottomRef, shouldUseKeyboardLayout);
 
   const appendContentDelta = useCallback((runId: string, delta: string, ts: number) => {
     beginContentArrival();
@@ -745,7 +755,7 @@ export default forwardRef<ChatInputHandle>(function Home(_props, forwardedRef) {
   }, [messages]);
 
   const showAppBackground = useDocumentScroll || !hideChrome;
-  const shellStyle = useDocumentScroll ? undefined : { height: isDetached ? "100%" : "100dvh" };
+  const shellStyle = shellHeight ? { height: shellHeight } : undefined;
 
   if (!turnstileChecked) return null;
   if (!turnstileVerified && TURNSTILE_SITE_KEY) {
@@ -763,7 +773,7 @@ export default forwardRef<ChatInputHandle>(function Home(_props, forwardedRef) {
   return (
     <div
       ref={appRef}
-      className={`relative flex flex-col ${useDocumentScroll ? "min-h-svh overflow-visible" : "overflow-hidden"} ${showAppBackground ? "bg-background" : ""}`}
+      className={`relative flex flex-col ${useDocumentScroll ? "min-h-svh overflow-visible" : "min-h-0 overflow-hidden"} ${showAppBackground ? "bg-background" : ""}`}
       style={shellStyle}
     >
       <ChatChrome
diff --git a/components/chat/ChatComposerBar.tsx b/components/chat/ChatComposerBar.tsx
index d400830..b3385d8 100644
--- a/components/chat/ChatComposerBar.tsx
+++ b/components/chat/ChatComposerBar.tsx
@@ -79,7 +79,7 @@ export function ChatComposerBar({
 }: ChatComposerBarProps) {
   if (isNative) return null;
 
-  const showScrollPill = scrollPhase === "pill";
+  const showScrollPill = useDocumentScroll && scrollPhase === "pill";
   const documentScrollClassName = "pointer-events-none relative z-20 flex justify-center px-3 md:px-6 animate-[fadeIn_400ms_ease-out]";
   const wrapperClassName = useDocumentScroll
     ? documentScrollClassName
@@ -110,6 +110,11 @@ export function ChatComposerBar({
       </button>
     </div>
   ) : null;
+  const composerWidthStyle = useDocumentScroll
+    ? ({ maxWidth: "42rem" } as React.CSSProperties)
+    : ({
+        maxWidth: "min(calc(200px + (100% - 200px) * (1 - var(--lp, 0))), calc(200px + (42rem - 200px) * (1 - var(--lp, 0))))",
+      } as React.CSSProperties);
 
   const renderComposer = (ref: React.RefObject<HTMLDivElement | null>) => (
     <div
@@ -120,7 +125,7 @@ export function ChatComposerBar({
       <div
         ref={morphRef}
         className="pointer-events-auto w-full"
-        style={{ maxWidth: "42rem" } as React.CSSProperties}
+        style={composerWidthStyle}
       >
         {pinnedSubagent && (
           <div style={{ paddingLeft: "calc(48px * (1 - var(--lp, 0)))", paddingRight: "calc(48px * (1 - var(--lp, 0)))" } as React.CSSProperties}>
diff --git a/components/chat/ChatViewport.tsx b/components/chat/ChatViewport.tsx
index 7870340..da7256b 100644
--- a/components/chat/ChatViewport.tsx
+++ b/components/chat/ChatViewport.tsx
@@ -694,7 +694,7 @@ export function ChatViewport({
       className={`relative flex flex-col ${useDocumentScroll ? "" : "flex-1 min-h-0"} ${detachedShell ? "px-3 pt-3" : ""}`}
     >
 
-      {!isNative && !useDocumentScroll && <div className={`pointer-events-none absolute z-20 h-7 opacity-60 ${detachedShell ? "inset-x-3 rounded-b-2xl" : "inset-x-0"}`} style={{ bottom: isDetached ? inputZoneHeight : 0, background: "linear-gradient(to top, var(--background) 40%, transparent)" }} />}
+      {!isNative && !useDocumentScroll && !detachedNoBorder && <div className={`pointer-events-none absolute z-20 h-7 opacity-60 ${detachedShell ? "inset-x-3 rounded-b-2xl" : "inset-x-0"}`} style={{ bottom: isDetached ? inputZoneHeight : 0, background: "linear-gradient(to top, var(--background) 40%, transparent)" }} />}
       <main
         ref={scrollRef}
         onScroll={useDocumentScroll ? undefined : () => {
@@ -705,7 +705,7 @@ export function ChatViewport({
             onNativeScrollPosition(distFromBottom);
           }
         }}
-        className={`scrollbar-hide ${useDocumentScroll ? "overflow-visible" : "flex-1 overflow-y-auto overflow-x-hidden"} ${isNative ? "" : "bg-background"} ${detachedShell ? "rounded-2xl" : (!isDetached ? "pt-14" : "")}`}
+        className={`scrollbar-hide ${useDocumentScroll ? "overflow-visible" : "flex-1 overflow-y-auto overflow-x-hidden"} ${isNative || detachedNoBorder ? "" : "bg-background"} ${detachedShell ? "rounded-2xl" : (!isDetached ? "pt-14" : "")}`}
         style={{ ...(isNative || useDocumentScroll ? {} : { overscrollBehavior: "none" as const }), ...(detachedShell ? { boxShadow: "0 -4px 6px -1px rgb(0 0 0 / 0.06), 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)" } : {}) }}
       >
         <div className={`mx-auto flex w-full ${isDetached || isNative ? "max-w-none" : "max-w-2xl"} flex-col gap-3 px-4 py-6 md:px-6 md:py-4 transition-opacity duration-300 ease-out ${historyLoaded ? "opacity-100" : "opacity-0"}`} style={{ paddingBottom: bottomPad }}>
@@ -871,7 +871,7 @@ export function ChatViewport({
         </div>
       </main>
 
-      {isDetached && !isNative && !useDocumentScroll && <div style={{ height: inputZoneHeight, flexShrink: 0 }} />}
+      {isDetached && !detachedNoBorder && !isNative && !useDocumentScroll && <div style={{ height: inputZoneHeight, flexShrink: 0 }} />}
 
       {!isDetached && !isNative && (
         <div
diff --git a/dev-notes/2026-03-25_ios-safari-detached-document-scroll-chat.md b/dev-notes/2026-03-25_ios-safari-detached-document-scroll-chat.md
index f5dcf52..f438645 100644
--- a/dev-notes/2026-03-25_ios-safari-detached-document-scroll-chat.md
+++ b/dev-notes/2026-03-25_ios-safari-detached-document-scroll-chat.md
@@ -66,6 +66,10 @@ Once document scroll owned the page, the previous `visualViewport.resize` / `foc
 
 On iOS Safari, tapping the floating jump pill during active momentum scroll may require a second tap because the first tap is consumed by inertia cancellation. This appears to be browser behavior rather than a chat-specific bug.
 
-## Follow-Up
+## Desktop Follow-Up
 
-- BUG: Scrolling in detached mode on desktop no longer works.
+Detached desktop stays on the old shell path.
+
+- standalone `?detached` desktop now uses a declarative `100dvh` shell instead of relying on an imperative height override
+- embedded/widget detached desktop still uses `height: 100%` so it honors the host container
+- mobile detached still uses document scroll
diff --git a/hooks/useAppMode.ts b/hooks/useAppMode.ts
index b4a8b18..724521d 100644
--- a/hooks/useAppMode.ts
+++ b/hooks/useAppMode.ts
@@ -1,5 +1,6 @@
 import { useState, useRef, useEffect } from "react";
 import { useWidgetContext } from "@mc/lib/widgetContext";
+import type { DetachedSurface } from "@mc/lib/chat/layoutMode";
 
 /** Read a URL search param. Only call on the client. */
 function getSearchParam(name: string): string | null {
@@ -32,6 +33,7 @@ function getUrlAppMode(): InitialAppMode {
 export interface AppMode {
   isDetached: boolean;
   detachedNoBorder: boolean;
+  detachedSurface: DetachedSurface;
   isNative: boolean;
   uploadDisabled: boolean;
   hideChrome: boolean;
@@ -41,6 +43,7 @@ export interface AppMode {
 
 export function useAppMode(): AppMode {
   const widgetCtx = useWidgetContext();
+  const detachedSurface: DetachedSurface = widgetCtx ? "widget" : "url";
 
   // When embedded via WidgetContextProvider, use context values as initial state
   // so the first render (including SSR) is already correct — no flash, no hydration mismatch.
@@ -98,6 +101,7 @@ export function useAppMode(): AppMode {
   return {
     isDetached: mode.isDetached,
     detachedNoBorder: mode.detachedNoBorder,
+    detachedSurface,
     isNative: mode.isNative,
     uploadDisabled: mode.uploadDisabled,
     hideChrome,
diff --git a/lib/chat/layoutMode.ts b/lib/chat/layoutMode.ts
new file mode 100644
index 0000000..ef8f280
--- /dev/null
+++ b/lib/chat/layoutMode.ts
@@ -0,0 +1,41 @@
+export type DetachedSurface = "url" | "widget";
+
+export type ChatLayoutMode = "document-scroll" | "viewport-shell" | "parent-shell";
+
+interface ChatLayoutConfigOptions {
+  isDetached: boolean;
+  isNative: boolean;
+  isMobileViewport: boolean;
+  detachedSurface: DetachedSurface;
+}
+
+interface ChatLayoutConfig {
+  mode: ChatLayoutMode;
+  useDocumentScroll: boolean;
+  shellHeight: "100dvh" | "100%" | null;
+  useKeyboardLayout: boolean;
+}
+
+export function getChatLayoutConfig({
+  isDetached,
+  isNative,
+  isMobileViewport,
+  detachedSurface,
+}: ChatLayoutConfigOptions): ChatLayoutConfig {
+  let mode: ChatLayoutMode;
+
+  if (!isDetached || isNative) {
+    mode = "viewport-shell";
+  } else if (isMobileViewport) {
+    mode = "document-scroll";
+  } else {
+    mode = detachedSurface === "widget" ? "parent-shell" : "viewport-shell";
+  }
+
+  return {
+    mode,
+    useDocumentScroll: mode === "document-scroll",
+    shellHeight: mode === "document-scroll" ? null : mode === "parent-shell" ? "100%" : "100dvh",
+    useKeyboardLayout: !isNative && isMobileViewport && mode !== "document-scroll",
+  };
+}
diff --git a/tests/layoutMode.test.ts b/tests/layoutMode.test.ts
new file mode 100644
index 0000000..15b429c
--- /dev/null
+++ b/tests/layoutMode.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+
+import { getChatLayoutConfig } from "@mc/lib/chat/layoutMode";
+
+describe("chat layout mode selection", () => {
+  it("uses document scroll for detached mobile url mode", () => {
+    expect(getChatLayoutConfig({
+      isDetached: true,
+      isNative: false,
+      isMobileViewport: true,
+      detachedSurface: "url",
+    })).toEqual({
+      mode: "document-scroll",
+      useDocumentScroll: true,
+      shellHeight: null,
+      useKeyboardLayout: false,
+    });
+  });
+
+  it("uses a viewport shell for detached desktop url mode", () => {
+    expect(getChatLayoutConfig({
+      isDetached: true,
+      isNative: false,
+      isMobileViewport: false,
+      detachedSurface: "url",
+    })).toEqual({
+      mode: "viewport-shell",
+      useDocumentScroll: false,
+      shellHeight: "100dvh",
+      useKeyboardLayout: false,
+    });
+  });
+
+  it("keeps embedded detached desktop on parent-fill shell mode", () => {
+    expect(getChatLayoutConfig({
+      isDetached: true,
+      isNative: false,
+      isMobileViewport: false,
+      detachedSurface: "widget",
+    })).toEqual({
+      mode: "parent-shell",
+      useDocumentScroll: false,
+      shellHeight: "100%",
+      useKeyboardLayout: false,
+    });
+  });
+
+  it("keeps existing non-detached and native behavior on the shell path", () => {
+    expect(getChatLayoutConfig({
+      isDetached: false,
+      isNative: false,
+      isMobileViewport: true,
+      detachedSurface: "url",
+    })).toEqual({
+      mode: "viewport-shell",
+      useDocumentScroll: false,
+      shellHeight: "100dvh",
+      useKeyboardLayout: true,
+    });
+
+    expect(getChatLayoutConfig({
+      isDetached: true,
+      isNative: true,
+      isMobileViewport: true,
+      detachedSurface: "url",
+    })).toEqual({
+      mode: "viewport-shell",
+      useDocumentScroll: false,
+      shellHeight: "100dvh",
+      useKeyboardLayout: false,
+    });
+  });
+});