From fa8cf7b82c90835a7be7ff4a8f60dd56698253de Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 8 Nov 2026 07:56:41 -0800
Subject: [PATCH 01/16] fix(ChatLayout): Safari reveals a document-scrolling
 composer

In a page that scrolls the document, Safari on iOS pans the visual
viewport to the fixed dock when the keyboard opens, and keeps the pan.
ChatLayout's lift added to that pan, so the composer went under the
status bar. Where no layout guide publishes the keyboard's slide,
ChatLayout now leaves the tap, the reveal and the dock's place to the
browser in that mode. With the VirtualKeyboard API, as in Chrome on
Android, and in self-scroll mode, nothing changes. AST-099 FR3 states
it.
---
 ...-layout-document-scroll-safari-keyboard.md |  6 ++
 docs/specs/AST-099-mobile-keyboard/spec.md    |  7 +-
 packages/core/src/Chat/ChatLayout.doc.mjs     |  4 +-
 packages/core/src/Chat/ChatLayout.tsx         |  2 +-
 .../core/src/Chat/useChatKeyboard.test.tsx    | 71 +++++++++++++++++++
 packages/core/src/Chat/useChatKeyboard.ts     | 55 +++++++++++---
 6 files changed, 132 insertions(+), 13 deletions(-)
 create mode 100644 .changeset/chat-layout-document-scroll-safari-keyboard.md

diff --git a/.changeset/chat-layout-document-scroll-safari-keyboard.md b/.changeset/chat-layout-document-scroll-safari-keyboard.md
new file mode 100644
index 0000000000000..a4c90a021e1ef
--- /dev/null
+++ b/.changeset/chat-layout-document-scroll-safari-keyboard.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] **ChatLayout**: In a page that scrolls the document (`scrollRef`), the composer stays right above the software keyboard in Safari on iOS, instead of jumping under the status bar.
+@vjeux
diff --git a/docs/specs/AST-099-mobile-keyboard/spec.md b/docs/specs/AST-099-mobile-keyboard/spec.md
index c9452a16e94ee..4ff93e8234cda 100644
--- a/docs/specs/AST-099-mobile-keyboard/spec.md
+++ b/docs/specs/AST-099-mobile-keyboard/spec.md
@@ -100,7 +100,12 @@ app to turn on.
   component applies it on its own element, such as a bottom offset, a padding,
   or a maximum height, so layout is correct with no animation running: the chat
   composer, a search field placed at the bottom, and tab bar search position
-  from it, and a fully expanded sheet extends its own scroll range by it. FR9's
+  from it, and a fully expanded sheet extends its own scroll range by it. In a
+  page that scrolls the document, in a browser without the VirtualKeyboard API,
+  ChatLayout lifts its dock by nothing. It leaves focus and the reveal to the
+  browser there: the composer is not a keyboard-aware surface (FR4). Safari on
+  iOS pans the visual viewport to the fixed dock and keeps the pan, which places
+  the composer above the keyboard. FR9's
   docked ride is the one exception: Core moves an app's docked bar as FR9 sets
   out. How the value reaches styles is `architecture:react-component-runtime`
   INV11. Riding the keyboard's motion layers on top of that layout, so layout
diff --git a/packages/core/src/Chat/ChatLayout.doc.mjs b/packages/core/src/Chat/ChatLayout.doc.mjs
index 4c6aab35abef5..3c2d84a2763e1 100644
--- a/packages/core/src/Chat/ChatLayout.doc.mjs
+++ b/packages/core/src/Chat/ChatLayout.doc.mjs
@@ -6,7 +6,7 @@ export const docs = {
   name: 'ChatLayout',
   subComponentOf: 'Chat',
   displayName: 'Chat Layout',
-  description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Set density (compact/balanced/spacious) to control spacing, message max-width, and blur layer sizing. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body. Where the visual viewport shrinks for the software keyboard, the composer stays on top of the keyboard, and a conversation at its newest message stays there. In Chrome on Android the composer rides Gboard\u2019s slides in step with them. In Safari on iOS (in the browser and as a home-screen app) and in Firefox for Android, it moves above the keyboard once the browser reports it. On a touch screen, in a top-level page, every way into the composer\u2019s text (a tap, the keyboard\u2019s previous and next buttons, Tab, the input\u2019s focus()) focuses it without scrolling the page; under a mouse or inside an iframe the browser\u2019s own focus applies. Where your page sets interactive-widget=resizes-content, Chrome on Android shrinks the page for the keyboard itself and the composer stays above it without moving (see the browser-support guide).',
+  description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Set density (compact/balanced/spacious) to control spacing, message max-width, and blur layer sizing. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body. Where the visual viewport shrinks for the software keyboard, the composer stays on top of the keyboard, and a conversation at its newest message stays there. In Chrome on Android the composer rides Gboard\u2019s slides in step with them. In Safari on iOS (in the browser and as a home-screen app) and in Firefox for Android, it moves above the keyboard once the browser reports it; in a page that scrolls the document (scrollRef), the browser reveals the composer itself there. On a touch screen, in a top-level page, every way into the composer\u2019s text (a tap, the keyboard\u2019s previous and next buttons, Tab, the input\u2019s focus()) focuses it without scrolling the page; under a mouse or inside an iframe the browser\u2019s own focus applies. Where your page sets interactive-widget=resizes-content, Chrome on Android shrinks the page for the keyboard itself and the composer stays above it without moving (see the browser-support guide).',
   props: [
     {
       name: 'children',
@@ -135,7 +135,7 @@ export const docsZh = {
 export const docsDense = {
   name: 'ChatLayout',
   displayName: 'Chat Layout',
-  description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; density prop (default balanced); scrollRef delegates to parent/body; in Chrome on Android (Gboard) the composer rides the software keyboard in step; in Safari on iOS and Firefox for Android it moves above the keyboard once reported (Chrome with interactive-widget=resizes-content: the page resizes, no move); transcript stays at newest msg, on a touch screen in a top-level page every focus route (tap, prev/next, Tab, focus()) w/o page scroll and Done rests focus on the composer group (no name, ring after keyboard input only, no tab stop); under a mouse or in an iframe: plain wrapper, browser focus',
+  description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; density prop (default balanced); scrollRef delegates to parent/body; in Chrome on Android (Gboard) the composer rides the software keyboard in step; in Safari on iOS and Firefox for Android it moves above the keyboard once reported (with scrollRef the browser reveals it) (Chrome with interactive-widget=resizes-content: the page resizes, no move); transcript stays at newest msg, on a touch screen in a top-level page every focus route (tap, prev/next, Tab, focus()) w/o page scroll and Done rests focus on the composer group (no name, ring after keyboard input only, no tab stop); under a mouse or in an iframe: plain wrapper, browser focus',
   usage: {
     bestPractices: [
       {guidance: true, description: 'Pass ChatMessageList as children and ChatComposer as composer prop for complete chat.'},
diff --git a/packages/core/src/Chat/ChatLayout.tsx b/packages/core/src/Chat/ChatLayout.tsx
index 4469396c2a9a9..9124d076a97df 100644
--- a/packages/core/src/Chat/ChatLayout.tsx
+++ b/packages/core/src/Chat/ChatLayout.tsx
@@ -448,7 +448,7 @@ export function ChatLayout({
           {/* The composer's region. Under a finger in a top-level page,
               useChatKeyboard makes it a group with no name, where focus rests
               after the keyboard's Done. Elsewhere it is a plain container. */}
-          <KeyboardSurfaceContext value={true}>
+          <KeyboardSurfaceContext value={keyboard.isKeyboardSurface}>
             <div
               ref={keyboard.composerRef}
               {...stylex.props(
diff --git a/packages/core/src/Chat/useChatKeyboard.test.tsx b/packages/core/src/Chat/useChatKeyboard.test.tsx
index c97ec8e1bdf4f..580dd91d11d99 100644
--- a/packages/core/src/Chat/useChatKeyboard.test.tsx
+++ b/packages/core/src/Chat/useChatKeyboard.test.tsx
@@ -348,6 +348,77 @@ describe('ChatLayout and the software keyboard', () => {
   });
 });
 
+describe('ChatLayout in a page that scrolls the document', () => {
+  beforeEach(() => {
+    // A phone: its primary pointer is a coarse finger.
+    vi.stubGlobal('matchMedia', (query: string) => ({
+      matches: query === '(pointer: coarse)',
+      media: query,
+      addEventListener: () => {},
+      removeEventListener: () => {},
+    }));
+    viewport = Object.assign(new EventTarget(), {
+      height: window.innerHeight,
+      offsetTop: 0,
+      scale: 1,
+    });
+    Object.defineProperty(window, 'visualViewport', {
+      configurable: true,
+      value: viewport,
+    });
+  });
+
+  afterEach(() => {
+    Reflect.deleteProperty(window, 'visualViewport');
+    Reflect.deleteProperty(navigator, 'virtualKeyboard');
+    vi.unstubAllGlobals();
+  });
+
+  function renderDocumentLayout() {
+    return render(
+      <ChatLayout
+        data-testid="layout"
+        scrollRef={{current: document.documentElement}}
+        composer={
+          <div data-testid="composer">
+            <textarea aria-label="Message" />
+          </div>
+        }>
+        <p>Hello</p>
+      </ChatLayout>,
+    );
+  }
+
+  it('lifts the fixed dock nothing in Safari on iOS, whose reveal pans the visual viewport to it and keeps the pan', async () => {
+    const {container} = renderDocumentLayout();
+    // Safari's reveal: the keyboard's report comes with a pan by its height.
+    viewport.offsetTop = 300;
+    report(window.innerHeight - 300);
+    await settle();
+    expect(layoutLift(dockOf(container))).toBe(0);
+    expect(keyboardRoom(messagesOf())).toBe(0);
+  });
+
+  it('leaves the composer\u2019s focus to Safari there: no focus takeover and no composer group', () => {
+    renderDocumentLayout();
+    const region = screen.getByTestId('composer').parentElement!.parentElement!;
+    expect(__focusTakeoverCallersForTest(document)).toBe(0);
+    expect(region.getAttribute('role')).toBeNull();
+  });
+
+  it('lifts the fixed dock by the keyboard with the VirtualKeyboard API, as in Chrome on Android', async () => {
+    Object.defineProperty(navigator, 'virtualKeyboard', {
+      configurable: true,
+      value: {overlaysContent: false},
+    });
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 300);
+    await settle();
+    expect(layoutLift(dockOf(container))).toBe(300);
+    expect(keyboardRoom(messagesOf())).toBe(300);
+  });
+});
+
 describe('focus moves into the composer (spec:AST-099 FR4)', () => {
   // The primary pointer `matchMedia` reports: a touch screen's coarse finger,
   // or a desktop's fine mouse.
diff --git a/packages/core/src/Chat/useChatKeyboard.ts b/packages/core/src/Chat/useChatKeyboard.ts
index 3ee04a7637e0b..3209773aaec03 100644
--- a/packages/core/src/Chat/useChatKeyboard.ts
+++ b/packages/core/src/Chat/useChatKeyboard.ts
@@ -8,7 +8,8 @@
  *   guide, the stream scroll's lock, the motion engine, the touch query and
  *   layout viewport height
  * @output Exports useChatKeyboard: the lift for ChatLayout's dock and message
- *   area, and the refs for its dock, message area and composer region
+ *   area, and the refs for its dock, message area and composer region. It
+ *   also tells whether a focus call in the composer skips the browser's reveal
  * @position ChatLayout's keyboard behavior (Chat/ChatLayout.tsx); internal
  *
  * The composer sits on the keyboard, as in Messages on iOS. Where the layout
@@ -80,6 +81,11 @@ export interface UseChatKeyboardResult {
    * focus on it.
    */
   composerRef: RefObject<HTMLDivElement | null>;
+  /**
+   * Whether a focus call in the composer skips the browser's reveal: false
+   * where the browser keeps the composer above the keyboard itself.
+   */
+  isKeyboardSurface: boolean;
 }
 
 // The lift the layout shows: a store the ride's end and keyboard reports
@@ -223,9 +229,11 @@ export function useChatKeyboard({
     // A sticky dock rests at the root's bottom edge, which may sit above or
     // below the layout viewport's; a fixed dock rests at the viewport's.
     // While a keyboard is up the dock rises until it clears the keyboard's
-    // cover; without one it rests where the layout puts it.
+    // cover; without one it rests where the layout puts it. Where the browser
+    // reveals the composer itself, the dock rises nothing.
+    const leavesReveal = leavesRevealToBrowser(win, isSelfScrolling);
     const liftFor = (inset: number) => {
-      if (inset <= 0) {
+      if (inset <= 0 || leavesReveal) {
         return 0;
       }
       // In layout px, as the root's rect is, under a pinch zoom too.
@@ -401,7 +409,8 @@ export function useChatKeyboard({
     if (
       !touchPresentation.isTouch ||
       composer == null ||
-      !followsKeyboard(win)
+      !followsKeyboard(win) ||
+      leavesRevealToBrowser(win, isSelfScrolling)
     ) {
       return undefined;
     }
@@ -409,7 +418,7 @@ export function useChatKeyboard({
       claim: editableToClaim,
       deliver: deliverTap,
     });
-  }, [touchPresentation.isTouch]);
+  }, [touchPresentation.isTouch, isSelfScrolling]);
 
   // A browser that reveals the composer itself pans the visual viewport after
   // the keyboard's report, while the composer still rides up. Chrome 124 on
@@ -422,7 +431,8 @@ export function useChatKeyboard({
     if (
       !touchPresentation.isTouch ||
       composer == null ||
-      !followsKeyboard(win)
+      !followsKeyboard(win) ||
+      leavesRevealToBrowser(win, isSelfScrolling)
     ) {
       return undefined;
     }
@@ -436,7 +446,7 @@ export function useChatKeyboard({
       unsubscribe();
       pans.stop();
     };
-  }, [touchPresentation.isTouch]);
+  }, [touchPresentation.isTouch, isSelfScrolling]);
 
   // Synchronizes the keyboard module's focus takeover, and the region's group
   // role, with the touch presentation. Every other move into the composer's
@@ -451,7 +461,8 @@ export function useChatKeyboard({
     if (
       !touchPresentation.isTouch ||
       composer == null ||
-      !followsKeyboard(win)
+      !followsKeyboard(win) ||
+      leavesRevealToBrowser(win, isSelfScrolling)
     ) {
       return undefined;
     }
@@ -471,16 +482,42 @@ export function useChatKeyboard({
       stopTakeover();
       composer.removeAttribute('role');
     };
-  }, [touchPresentation.isTouch, readModality]);
+  }, [touchPresentation.isTouch, readModality, isSelfScrolling]);
+
+  // A focus call skips the browser's reveal only where ChatLayout keeps the
+  // composer above the keyboard itself. The server has no keyboard profile.
+  const hasLayoutGuide = useSyncExternalStore(
+    subscribeToNothing,
+    readLayoutGuide,
+    readNoLayoutGuide,
+  );
+  const isKeyboardSurface = isSelfScrolling || hasLayoutGuide;
 
   return {
     lift,
     dockRef: dock.ref,
     messagesRef: messages.ref,
     composerRef,
+    isKeyboardSurface,
   };
 }
 
+// A browser's keyboard profile never changes while the page runs.
+const subscribeToNothing = () => () => {};
+const readLayoutGuide = () => keyboardProfileOf(window) === 'chromium';
+const readNoLayoutGuide = () => false;
+
+/**
+ * Whether the browser keeps the composer above the keyboard itself. That is a
+ * page that scrolls the document, in a browser with no layout guide, such as
+ * Safari on iOS. Safari pans the visual viewport to the fixed dock and keeps
+ * the pan. A lift would add to that pan. So ChatLayout leaves focus, the
+ * reveal and the dock's place to the browser there.
+ */
+function leavesRevealToBrowser(win: Window, isSelfScrolling: boolean): boolean {
+  return !isSelfScrolling && keyboardProfileOf(win) !== 'chromium';
+}
+
 /** A compositor animator for one element, bound through a stable callback ref. */
 function useElementAnimator(): {
   readonly ref: (element: HTMLElement | null) => void;

From 2c514fbef49bc3b6c0c0f9a46a79af0134ec524a Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 8 Nov 2026 08:49:46 -0800
Subject: [PATCH 02/16] fix(ChatLayout): only the document's scroller leaves
 Safari the reveal

The exception now applies only when scrollRef names the document's own
scroller: its root or its body. A scrollRef on an inner scrolling
element keeps the lift, the tap claim and the focus takeover. The docs
name the exception for Safari on iOS, in both languages. AST-099 FR9's
docked-container clause and the FR3-FR4 verification row name it too.
---
 docs/specs/AST-099-mobile-keyboard/spec.md    |  6 ++-
 packages/core/src/Chat/ChatLayout.doc.mjs     |  6 +--
 .../core/src/Chat/useChatKeyboard.test.tsx    | 25 +++++++++
 packages/core/src/Chat/useChatKeyboard.ts     | 54 +++++++++++++------
 4 files changed, 70 insertions(+), 21 deletions(-)

diff --git a/docs/specs/AST-099-mobile-keyboard/spec.md b/docs/specs/AST-099-mobile-keyboard/spec.md
index 4ff93e8234cda..a04d8341e57b9 100644
--- a/docs/specs/AST-099-mobile-keyboard/spec.md
+++ b/docs/specs/AST-099-mobile-keyboard/spec.md
@@ -206,7 +206,9 @@ app to turn on.
     FR8's ride (DEC-2) where that applies, and following the visual-viewport
     height (FR2) elsewhere, such as Safari on iOS. A Core host rides by applying
     the keyboard height on its own element (FR3), and the field inside it is not
-    moved a second time.
+    moved a second time. FR3 names one exception: ChatLayout's dock in a page
+    that scrolls the document, in a browser without the VirtualKeyboard API.
+    There the browser's reveal places it.
   - **App-owned docked containers.** A container the app owns rides too when it
     is fixed-position, does not fill the viewport, and is docked: its layout
     box, before any transform, sits at the viewport's bottom edge. A docked
@@ -403,7 +405,7 @@ that sets its own `translate`, to the app.
 | FR8      | Firefox for Android in the emulator, top-level document                                                      | focus routes, keyboard shown and hidden, page panned and pinch-zoomed, a sheet moved                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | The page lurches, the field ends under the keyboard, or the height is wrong after a pan or zoom                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | FR2–FR5  | Safari on iOS in the iOS Simulator or on a device, top-level document                                        | focus routes, keyboard shown and hidden, page panned and pinch-zoomed, a sheet moved, ChatLayout's composer, in Safari and as a home-screen app                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | The page lurches, the field ends under the keyboard, or the height is wrong after a pan or zoom                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | FR2–FR5  | Release gate: a physical iPhone in a top-level document (DEC-3)                                              | iPhone Safari with the toolbar expanded and collapsed; iPhone home-screen app; the phone's refresh rate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | The page lurches, the field ends under the keyboard, or the surface does not follow the keyboard                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| FR3–FR4  | ChatLayout's keyboard tests in jsdom and its interaction proofs in Chromium and WebKit                       | the fixed and the sticky dock with the keyboard shown and hidden; the message area's end padding; a transcript at its newest message; a page pinch-zoomed with the keyboard up; focus by tap, Tab, `focus()` and Done, under a finger and under a mouse                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | The dock left under the keyboard or lifted with none; the newest message unable to scroll above the composer; a transcript at its newest message left behind; the page panned to the composer's text under a finger; focus left in the text after Done, or the composer group focusable outside Done's park                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| FR3–FR4  | ChatLayout's keyboard tests in jsdom and its interaction proofs in Chromium and WebKit                       | the fixed and the sticky dock with the keyboard shown and hidden; the message area's end padding; a transcript at its newest message; a page pinch-zoomed with the keyboard up; focus by tap, Tab, `focus()` and Done, under a finger and under a mouse                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | The dock left under the keyboard or lifted with none; the newest message unable to scroll above the composer; a transcript at its newest message left behind; the page panned to the composer's text under a finger, outside FR3's document-scroll exception; focus left in the text after Done, or the composer group focusable outside Done's park                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | FR8      | ChatLayout's interaction proofs in Chromium with Chrome's keyboard report                                    | the dock riding Gboard's slide up from the report and down from the blur; reduced motion on                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | The dock lagging Gboard's slide, laying out or painting per frame, or jumping at the hand-back; the dock travelling under reduced motion instead of DR2's cross-fade                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | FR9      | ChatLayout's keyboard tests in jsdom                                                                         | ChatComposer in the fixed and the sticky dock, above the keyboard after each focus route                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | ChatComposer ending under the keyboard, or moved a second time inside its dock, after any focus route                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | FR9      | TBD (Gap 1–11): a focus test per covered field, driving one keyboard change                                  | each covered field in the page, a Tall and a `hug` BottomSheet, ChatLayout's fixed and sticky dock, an app's fixed bar docked to the bottom edge with no `translate` of its own, and a fixed Toolbar docked there; focus by tap, Tab, and `focus()`; a field in scrolling content in the page and in a nested scroller; a field near its scroller's end; a field in a scroller inside a full-viewport fixed container                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | A focused page field or Core-host field left under the keyboard or less than 10 CSS px above it (a field with no scroller between it and a fixed container FR9 leaves to the app keeps the browser's own reveal and is not a failure; a field that a scroller holds inside such a container, left under the keyboard, is a failure), a field in an app's docked bar whose bar's bottom does not meet the keyboard's top, scroll range left at the scroller's end after the keyboard hides, a page pan or translate, a reveal later than the frame the keyboard is reported in, or a second offset inside a host that already applies the height                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
diff --git a/packages/core/src/Chat/ChatLayout.doc.mjs b/packages/core/src/Chat/ChatLayout.doc.mjs
index 3c2d84a2763e1..b0460efc9f4fa 100644
--- a/packages/core/src/Chat/ChatLayout.doc.mjs
+++ b/packages/core/src/Chat/ChatLayout.doc.mjs
@@ -6,7 +6,7 @@ export const docs = {
   name: 'ChatLayout',
   subComponentOf: 'Chat',
   displayName: 'Chat Layout',
-  description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Set density (compact/balanced/spacious) to control spacing, message max-width, and blur layer sizing. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body. Where the visual viewport shrinks for the software keyboard, the composer stays on top of the keyboard, and a conversation at its newest message stays there. In Chrome on Android the composer rides Gboard\u2019s slides in step with them. In Safari on iOS (in the browser and as a home-screen app) and in Firefox for Android, it moves above the keyboard once the browser reports it; in a page that scrolls the document (scrollRef), the browser reveals the composer itself there. On a touch screen, in a top-level page, every way into the composer\u2019s text (a tap, the keyboard\u2019s previous and next buttons, Tab, the input\u2019s focus()) focuses it without scrolling the page; under a mouse or inside an iframe the browser\u2019s own focus applies. Where your page sets interactive-widget=resizes-content, Chrome on Android shrinks the page for the keyboard itself and the composer stays above it without moving (see the browser-support guide).',
+  description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Set density (compact/balanced/spacious) to control spacing, message max-width, and blur layer sizing. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body. Where the visual viewport shrinks for the software keyboard, the composer stays on top of the keyboard, and a conversation at its newest message stays there. In Chrome on Android the composer rides Gboard\u2019s slides in step with them. In Safari on iOS (in the browser and as a home-screen app) and in Firefox for Android, it moves above the keyboard once the browser reports it. On a touch screen, in a top-level page, every way into the composer\u2019s text (a tap, the keyboard\u2019s previous and next buttons, Tab, the input\u2019s focus()) focuses it without scrolling the page; under a mouse or inside an iframe the browser\u2019s own focus applies. When scrollRef names the document, Safari on iOS reveals the composer itself: focus is the browser\u2019s, and Done rests it on no composer group. Where your page sets interactive-widget=resizes-content, Chrome on Android shrinks the page for the keyboard itself and the composer stays above it without moving (see the browser-support guide).',
   props: [
     {
       name: 'children',
@@ -121,7 +121,7 @@ export const docs = {
 export const docsZh = {
   name: 'ChatLayout',
   displayName: 'Chat Layout',
-  description: '完整聊天界面的布局外壳。消息在页面中自然流动，编写器固定在底部，带有毛玻璃效果。通过 density 属性控制密度。在可视视口会随软键盘缩小的浏览器中，编写器停在键盘上方，停留在最新消息的对话保持在最新消息。在 Android 上的 Chrome 中，编写器随 Gboard 的滑动同步移动。在 iOS 上的 Safari（浏览器中和添加到主屏幕的网页应用）和 Android 上的 Firefox 中，编写器会在浏览器报告键盘后移到键盘上方。在触摸屏上的顶层页面中，进入编写器文本的每种方式（轻点、键盘的上一项和下一项按钮、Tab、输入框的 focus()）都会聚焦它而不滚动页面；使用鼠标或在 iframe 中时沿用浏览器自身的聚焦行为。如果页面设置了 interactive-widget=resizes-content，Android 上的 Chrome 会自行为键盘缩小页面，编写器停在键盘上方而不移动（参见浏览器支持指南）。',
+  description: '完整聊天界面的布局外壳。消息在页面中自然流动，编写器固定在底部，带有毛玻璃效果。通过 density 属性控制密度。在可视视口会随软键盘缩小的浏览器中，编写器停在键盘上方，停留在最新消息的对话保持在最新消息。在 Android 上的 Chrome 中，编写器随 Gboard 的滑动同步移动。在 iOS 上的 Safari（浏览器中和添加到主屏幕的网页应用）和 Android 上的 Firefox 中，编写器会在浏览器报告键盘后移到键盘上方。在触摸屏上的顶层页面中，进入编写器文本的每种方式（轻点、键盘的上一项和下一项按钮、Tab、输入框的 focus()）都会聚焦它而不滚动页面；使用鼠标或在 iframe 中时沿用浏览器自身的聚焦行为。当 scrollRef 指向文档时，iOS 上的 Safari 会自行将编写器显示在键盘上方：聚焦沿用浏览器自身的行为，键盘的“完成”也不会把焦点停在编写器分组上。如果页面设置了 interactive-widget=resizes-content，Android 上的 Chrome 会自行为键盘缩小页面，编写器停在键盘上方而不移动（参见浏览器支持指南）。',
   propDescriptions: {
     children: '消息内容，通常是 ChatMessageList。在页面中自然流动。',
     composer: '编写器元素，通常是 ChatComposer。固定在底部，带有毛玻璃底座。',
@@ -135,7 +135,7 @@ export const docsZh = {
 export const docsDense = {
   name: 'ChatLayout',
   displayName: 'Chat Layout',
-  description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; density prop (default balanced); scrollRef delegates to parent/body; in Chrome on Android (Gboard) the composer rides the software keyboard in step; in Safari on iOS and Firefox for Android it moves above the keyboard once reported (with scrollRef the browser reveals it) (Chrome with interactive-widget=resizes-content: the page resizes, no move); transcript stays at newest msg, on a touch screen in a top-level page every focus route (tap, prev/next, Tab, focus()) w/o page scroll and Done rests focus on the composer group (no name, ring after keyboard input only, no tab stop); under a mouse or in an iframe: plain wrapper, browser focus',
+  description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; density prop (default balanced); scrollRef delegates to parent/body; in Chrome on Android (Gboard) the composer rides the software keyboard in step; in Safari on iOS and Firefox for Android it moves above the keyboard once reported (Chrome with interactive-widget=resizes-content: the page resizes, no move); transcript stays at newest msg, on a touch screen in a top-level page every focus route (tap, prev/next, Tab, focus()) w/o page scroll and Done rests focus on the composer group (no name, ring after keyboard input only, no tab stop); under a mouse or in an iframe: plain wrapper, browser focus; scrollRef on the document in Safari on iOS: Safari reveals the composer, browser focus, no group',
   usage: {
     bestPractices: [
       {guidance: true, description: 'Pass ChatMessageList as children and ChatComposer as composer prop for complete chat.'},
diff --git a/packages/core/src/Chat/useChatKeyboard.test.tsx b/packages/core/src/Chat/useChatKeyboard.test.tsx
index 580dd91d11d99..1d49198e4fb37 100644
--- a/packages/core/src/Chat/useChatKeyboard.test.tsx
+++ b/packages/core/src/Chat/useChatKeyboard.test.tsx
@@ -406,6 +406,31 @@ describe('ChatLayout in a page that scrolls the document', () => {
     expect(region.getAttribute('role')).toBeNull();
   });
 
+  it('keeps the lift and the focus takeover for a scrollRef on an inner scroller, in Safari on iOS too', async () => {
+    const scroller = document.createElement('div');
+    document.body.append(scroller);
+    try {
+      const {container} = render(
+        <ChatLayout
+          data-testid="layout"
+          scrollRef={{current: scroller}}
+          composer={
+            <div data-testid="composer">
+              <textarea aria-label="Message" />
+            </div>
+          }>
+          <p>Hello</p>
+        </ChatLayout>,
+      );
+      expect(__focusTakeoverCallersForTest(document)).toBe(1);
+      report(window.innerHeight - 300);
+      await settle();
+      expect(layoutLift(dockOf(container))).toBe(300);
+    } finally {
+      scroller.remove();
+    }
+  });
+
   it('lifts the fixed dock by the keyboard with the VirtualKeyboard API, as in Chrome on Android', async () => {
     Object.defineProperty(navigator, 'virtualKeyboard', {
       configurable: true,
diff --git a/packages/core/src/Chat/useChatKeyboard.ts b/packages/core/src/Chat/useChatKeyboard.ts
index 3209773aaec03..e473ea12aab1d 100644
--- a/packages/core/src/Chat/useChatKeyboard.ts
+++ b/packages/core/src/Chat/useChatKeyboard.ts
@@ -18,7 +18,13 @@
  * SYNC: update Chat/ChatLayout.tsx, ChatLayout.doc.mjs and keyboard/README.md
  */
 
-import {useRef, useState, useSyncExternalStore, type RefObject} from 'react';
+import {
+  useCallback,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type RefObject,
+} from 'react';
 import {createMotionEngine, type Animator} from '../motion/animator';
 import {
   claimTapFocus,
@@ -231,7 +237,7 @@ export function useChatKeyboard({
     // While a keyboard is up the dock rises until it clears the keyboard's
     // cover; without one it rests where the layout puts it. Where the browser
     // reveals the composer itself, the dock rises nothing.
-    const leavesReveal = leavesRevealToBrowser(win, isSelfScrolling);
+    const leavesReveal = leavesRevealToBrowser(win, scrollRef.current);
     const liftFor = (inset: number) => {
       if (inset <= 0 || leavesReveal) {
         return 0;
@@ -410,7 +416,7 @@ export function useChatKeyboard({
       !touchPresentation.isTouch ||
       composer == null ||
       !followsKeyboard(win) ||
-      leavesRevealToBrowser(win, isSelfScrolling)
+      leavesRevealToBrowser(win, scrollRef.current)
     ) {
       return undefined;
     }
@@ -418,7 +424,7 @@ export function useChatKeyboard({
       claim: editableToClaim,
       deliver: deliverTap,
     });
-  }, [touchPresentation.isTouch, isSelfScrolling]);
+  }, [touchPresentation.isTouch, scrollRef]);
 
   // A browser that reveals the composer itself pans the visual viewport after
   // the keyboard's report, while the composer still rides up. Chrome 124 on
@@ -432,7 +438,7 @@ export function useChatKeyboard({
       !touchPresentation.isTouch ||
       composer == null ||
       !followsKeyboard(win) ||
-      leavesRevealToBrowser(win, isSelfScrolling)
+      leavesRevealToBrowser(win, scrollRef.current)
     ) {
       return undefined;
     }
@@ -446,7 +452,7 @@ export function useChatKeyboard({
       unsubscribe();
       pans.stop();
     };
-  }, [touchPresentation.isTouch, isSelfScrolling]);
+  }, [touchPresentation.isTouch, scrollRef]);
 
   // Synchronizes the keyboard module's focus takeover, and the region's group
   // role, with the touch presentation. Every other move into the composer's
@@ -462,7 +468,7 @@ export function useChatKeyboard({
       !touchPresentation.isTouch ||
       composer == null ||
       !followsKeyboard(win) ||
-      leavesRevealToBrowser(win, isSelfScrolling)
+      leavesRevealToBrowser(win, scrollRef.current)
     ) {
       return undefined;
     }
@@ -482,16 +488,20 @@ export function useChatKeyboard({
       stopTakeover();
       composer.removeAttribute('role');
     };
-  }, [touchPresentation.isTouch, readModality, isSelfScrolling]);
+  }, [touchPresentation.isTouch, readModality, scrollRef]);
 
   // A focus call skips the browser's reveal only where ChatLayout keeps the
   // composer above the keyboard itself. The server has no keyboard profile.
-  const hasLayoutGuide = useSyncExternalStore(
+  const readKeyboardSurface = useCallback(() => {
+    const scroller = scrollRef.current;
+    const win = scroller?.ownerDocument.defaultView;
+    return win == null || !leavesRevealToBrowser(win, scroller);
+  }, [scrollRef]);
+  const isKeyboardSurface = useSyncExternalStore(
     subscribeToNothing,
-    readLayoutGuide,
-    readNoLayoutGuide,
+    readKeyboardSurface,
+    readKeyboardSurfaceOnServer,
   );
-  const isKeyboardSurface = isSelfScrolling || hasLayoutGuide;
 
   return {
     lift,
@@ -504,8 +514,7 @@ export function useChatKeyboard({
 
 // A browser's keyboard profile never changes while the page runs.
 const subscribeToNothing = () => () => {};
-const readLayoutGuide = () => keyboardProfileOf(window) === 'chromium';
-const readNoLayoutGuide = () => false;
+const readKeyboardSurfaceOnServer = () => true;
 
 /**
  * Whether the browser keeps the composer above the keyboard itself. That is a
@@ -514,8 +523,21 @@ const readNoLayoutGuide = () => false;
  * the pan. A lift would add to that pan. So ChatLayout leaves focus, the
  * reveal and the dock's place to the browser there.
  */
-function leavesRevealToBrowser(win: Window, isSelfScrolling: boolean): boolean {
-  return !isSelfScrolling && keyboardProfileOf(win) !== 'chromium';
+function leavesRevealToBrowser(win: Window, scroller: Element | null): boolean {
+  return isDocumentScroller(scroller) && keyboardProfileOf(win) !== 'chromium';
+}
+
+// The document's root and body both scroll the page.
+function isDocumentScroller(scroller: Element | null): boolean {
+  if (scroller == null) {
+    return false;
+  }
+  const doc = scroller.ownerDocument;
+  return (
+    scroller === doc.scrollingElement ||
+    scroller === doc.documentElement ||
+    scroller === doc.body
+  );
 }
 
 /** A compositor animator for one element, bound through a stable callback ref. */

From b143b86c013388987e2233f091ff900c31712af1 Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 8 Nov 2026 08:52:32 -0800
Subject: [PATCH 03/16] docs(AST-099): name the exception by ChatLayout's
 scrollRef

FR3 and FR9's docked-container clause now state the rule the code
keys on: ChatLayout's scrollRef names the document's scroller.
---
 docs/specs/AST-099-mobile-keyboard/spec.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/docs/specs/AST-099-mobile-keyboard/spec.md b/docs/specs/AST-099-mobile-keyboard/spec.md
index a04d8341e57b9..4b47ce8d371a4 100644
--- a/docs/specs/AST-099-mobile-keyboard/spec.md
+++ b/docs/specs/AST-099-mobile-keyboard/spec.md
@@ -100,12 +100,12 @@ app to turn on.
   component applies it on its own element, such as a bottom offset, a padding,
   or a maximum height, so layout is correct with no animation running: the chat
   composer, a search field placed at the bottom, and tab bar search position
-  from it, and a fully expanded sheet extends its own scroll range by it. In a
-  page that scrolls the document, in a browser without the VirtualKeyboard API,
-  ChatLayout lifts its dock by nothing. It leaves focus and the reveal to the
-  browser there: the composer is not a keyboard-aware surface (FR4). Safari on
-  iOS pans the visual viewport to the fixed dock and keeps the pan, which places
-  the composer above the keyboard. FR9's
+  from it, and a fully expanded sheet extends its own scroll range by it. When
+  ChatLayout's `scrollRef` names the document's scroller, in a browser without
+  the VirtualKeyboard API, ChatLayout lifts its dock by nothing. It leaves focus
+  and the reveal to the browser there: the composer is not a keyboard-aware
+  surface (FR4). Safari on iOS pans the visual viewport to the fixed dock and
+  keeps the pan, which places the composer above the keyboard. FR9's
   docked ride is the one exception: Core moves an app's docked bar as FR9 sets
   out. How the value reaches styles is `architecture:react-component-runtime`
   INV11. Riding the keyboard's motion layers on top of that layout, so layout
@@ -206,9 +206,9 @@ app to turn on.
     FR8's ride (DEC-2) where that applies, and following the visual-viewport
     height (FR2) elsewhere, such as Safari on iOS. A Core host rides by applying
     the keyboard height on its own element (FR3), and the field inside it is not
-    moved a second time. FR3 names one exception: ChatLayout's dock in a page
-    that scrolls the document, in a browser without the VirtualKeyboard API.
-    There the browser's reveal places it.
+    moved a second time. FR3 names one exception: ChatLayout's dock when its
+    `scrollRef` names the document's scroller, in a browser without the
+    VirtualKeyboard API. There the browser's reveal places it.
   - **App-owned docked containers.** A container the app owns rides too when it
     is fixed-position, does not fill the viewport, and is docked: its layout
     box, before any transform, sits at the viewport's bottom edge. A docked

From 37f7a9b9eeb44b563cae65562e18b9b351c207de Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 8 Nov 2026 09:24:21 -0800
Subject: [PATCH 04/16] docs(ChatLayout): name every browser the scrollRef
 exception covers

ChatLayout's docs, in English, Chinese and the dense line, and the
composer prop's description name the exception's real scope: a scrollRef
on the document in a browser without the VirtualKeyboard API, as Safari
on iOS and Firefox for Android. There ChatLayout leaves focus and the
reveal to the browser, with no composer group. The browser-support guide
names it beside the Firefox pan put-back.
---
 packages/cli/assets/docs/browser-support.doc.mjs | 2 +-
 packages/core/src/Chat/ChatLayout.doc.mjs        | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/cli/assets/docs/browser-support.doc.mjs b/packages/cli/assets/docs/browser-support.doc.mjs
index b55a912125e8d..69d9dba1d98f1 100644
--- a/packages/cli/assets/docs/browser-support.doc.mjs
+++ b/packages/cli/assets/docs/browser-support.doc.mjs
@@ -148,7 +148,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "On a phone, the components that respond to the on-screen keyboard, a fully expanded `height='tall'` BottomSheet and ChatLayout's composer, measure it the same way: the layout viewport's height minus the visual viewport's height times its scale. Where the visual viewport shrinks for the keyboard, as in Safari on iOS in the browser and as a home-screen app, in Firefox for Android and in Chrome on Android, they keep the focused field and the surface around it above the keyboard and leave the page where it was. If Firefox for Android pans to the field, they put the page back within a couple of frames.",
+          text: "On a phone, the components that respond to the on-screen keyboard, a fully expanded `height='tall'` BottomSheet and ChatLayout's composer, measure it the same way: the layout viewport's height minus the visual viewport's height times its scale. Where the visual viewport shrinks for the keyboard, as in Safari on iOS in the browser and as a home-screen app, in Firefox for Android and in Chrome on Android, they keep the focused field and the surface around it above the keyboard and leave the page where it was. If Firefox for Android pans to the field, they put the page back within a couple of frames. One exception applies when ChatLayout's scrollRef names the document. Then a browser without the VirtualKeyboard API keeps the composer's focus and reveal, as Safari on iOS and Firefox for Android do.",
         },
         {
           type: 'prose',
diff --git a/packages/core/src/Chat/ChatLayout.doc.mjs b/packages/core/src/Chat/ChatLayout.doc.mjs
index b0460efc9f4fa..34b01a5cacda0 100644
--- a/packages/core/src/Chat/ChatLayout.doc.mjs
+++ b/packages/core/src/Chat/ChatLayout.doc.mjs
@@ -6,7 +6,7 @@ export const docs = {
   name: 'ChatLayout',
   subComponentOf: 'Chat',
   displayName: 'Chat Layout',
-  description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Set density (compact/balanced/spacious) to control spacing, message max-width, and blur layer sizing. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body. Where the visual viewport shrinks for the software keyboard, the composer stays on top of the keyboard, and a conversation at its newest message stays there. In Chrome on Android the composer rides Gboard\u2019s slides in step with them. In Safari on iOS (in the browser and as a home-screen app) and in Firefox for Android, it moves above the keyboard once the browser reports it. On a touch screen, in a top-level page, every way into the composer\u2019s text (a tap, the keyboard\u2019s previous and next buttons, Tab, the input\u2019s focus()) focuses it without scrolling the page; under a mouse or inside an iframe the browser\u2019s own focus applies. When scrollRef names the document, Safari on iOS reveals the composer itself: focus is the browser\u2019s, and Done rests it on no composer group. Where your page sets interactive-widget=resizes-content, Chrome on Android shrinks the page for the keyboard itself and the composer stays above it without moving (see the browser-support guide).',
+  description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Set density (compact/balanced/spacious) to control spacing, message max-width, and blur layer sizing. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body. Where the visual viewport shrinks for the software keyboard, the composer stays on top of the keyboard, and a conversation at its newest message stays there. In Chrome on Android the composer rides Gboard\u2019s slides in step with them. In Safari on iOS (in the browser and as a home-screen app) and in Firefox for Android, it moves above the keyboard once the browser reports it. On a touch screen, in a top-level page, every way into the composer\u2019s text (a tap, the keyboard\u2019s previous and next buttons, Tab, the input\u2019s focus()) focuses it without scrolling the page; under a mouse or inside an iframe the browser\u2019s own focus applies. When scrollRef names the document, a browser without the VirtualKeyboard API keeps focus and the composer\u2019s reveal. Safari on iOS and Firefox for Android are such browsers. Done then rests focus on no composer group. Where your page sets interactive-widget=resizes-content, Chrome on Android shrinks the page for the keyboard itself and the composer stays above it without moving (see the browser-support guide).',
   props: [
     {
       name: 'children',
@@ -107,7 +107,7 @@ export const docs = {
       {
         name: 'Composer',
         required: true,
-        description: 'The input area for sending messages, typically ChatComposer. Docked at the bottom inside the frosted glass layer. In a top-level page on a touch screen, its wrapper (without the scroll button) is a group with no name. When the keyboard\u2019s Done ends typing, focus rests on that group (it is no tab stop), so the next tap or Tab starts from the composer. It shows the focus ring after keyboard input only. Under a mouse or inside an iframe, the wrapper is a plain container.',
+        description: 'The input area for sending messages, typically ChatComposer. Docked at the bottom inside the frosted glass layer. In a top-level page on a touch screen, its wrapper (without the scroll button) is a group with no name. When the keyboard\u2019s Done ends typing, focus rests on that group (it is no tab stop), so the next tap or Tab starts from the composer. It shows the focus ring after keyboard input only. Under a mouse or inside an iframe, the wrapper is a plain container. So it is when scrollRef names the document in a browser without the VirtualKeyboard API: the browser keeps focus there.',
       },
       {
         name: 'Empty state',
@@ -121,7 +121,7 @@ export const docs = {
 export const docsZh = {
   name: 'ChatLayout',
   displayName: 'Chat Layout',
-  description: '完整聊天界面的布局外壳。消息在页面中自然流动，编写器固定在底部，带有毛玻璃效果。通过 density 属性控制密度。在可视视口会随软键盘缩小的浏览器中，编写器停在键盘上方，停留在最新消息的对话保持在最新消息。在 Android 上的 Chrome 中，编写器随 Gboard 的滑动同步移动。在 iOS 上的 Safari（浏览器中和添加到主屏幕的网页应用）和 Android 上的 Firefox 中，编写器会在浏览器报告键盘后移到键盘上方。在触摸屏上的顶层页面中，进入编写器文本的每种方式（轻点、键盘的上一项和下一项按钮、Tab、输入框的 focus()）都会聚焦它而不滚动页面；使用鼠标或在 iframe 中时沿用浏览器自身的聚焦行为。当 scrollRef 指向文档时，iOS 上的 Safari 会自行将编写器显示在键盘上方：聚焦沿用浏览器自身的行为，键盘的“完成”也不会把焦点停在编写器分组上。如果页面设置了 interactive-widget=resizes-content，Android 上的 Chrome 会自行为键盘缩小页面，编写器停在键盘上方而不移动（参见浏览器支持指南）。',
+  description: '完整聊天界面的布局外壳。消息在页面中自然流动，编写器固定在底部，带有毛玻璃效果。通过 density 属性控制密度。在可视视口会随软键盘缩小的浏览器中，编写器停在键盘上方，停留在最新消息的对话保持在最新消息。在 Android 上的 Chrome 中，编写器随 Gboard 的滑动同步移动。在 iOS 上的 Safari（浏览器中和添加到主屏幕的网页应用）和 Android 上的 Firefox 中，编写器会在浏览器报告键盘后移到键盘上方。在触摸屏上的顶层页面中，进入编写器文本的每种方式（轻点、键盘的上一项和下一项按钮、Tab、输入框的 focus()）都会聚焦它而不滚动页面；使用鼠标或在 iframe 中时沿用浏览器自身的聚焦行为。当 scrollRef 指向文档，且浏览器没有 VirtualKeyboard API（iOS 上的 Safari、Android 上的 Firefox）时，ChatLayout 把聚焦和编写器的显示交给浏览器，键盘的“完成”也不会把焦点停在编写器分组上。如果页面设置了 interactive-widget=resizes-content，Android 上的 Chrome 会自行为键盘缩小页面，编写器停在键盘上方而不移动（参见浏览器支持指南）。',
   propDescriptions: {
     children: '消息内容，通常是 ChatMessageList。在页面中自然流动。',
     composer: '编写器元素，通常是 ChatComposer。固定在底部，带有毛玻璃底座。',
@@ -135,7 +135,7 @@ export const docsZh = {
 export const docsDense = {
   name: 'ChatLayout',
   displayName: 'Chat Layout',
-  description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; density prop (default balanced); scrollRef delegates to parent/body; in Chrome on Android (Gboard) the composer rides the software keyboard in step; in Safari on iOS and Firefox for Android it moves above the keyboard once reported (Chrome with interactive-widget=resizes-content: the page resizes, no move); transcript stays at newest msg, on a touch screen in a top-level page every focus route (tap, prev/next, Tab, focus()) w/o page scroll and Done rests focus on the composer group (no name, ring after keyboard input only, no tab stop); under a mouse or in an iframe: plain wrapper, browser focus; scrollRef on the document in Safari on iOS: Safari reveals the composer, browser focus, no group',
+  description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; density prop (default balanced); scrollRef delegates to parent/body; in Chrome on Android (Gboard) the composer rides the software keyboard in step; in Safari on iOS and Firefox for Android it moves above the keyboard once reported (Chrome with interactive-widget=resizes-content: the page resizes, no move); transcript stays at newest msg, on a touch screen in a top-level page every focus route (tap, prev/next, Tab, focus()) w/o page scroll and Done rests focus on the composer group (no name, ring after keyboard input only, no tab stop); under a mouse or in an iframe: plain wrapper, browser focus; scrollRef on the document without the VirtualKeyboard API (Safari on iOS, Firefox for Android): browser focus and reveal, no group',
   usage: {
     bestPractices: [
       {guidance: true, description: 'Pass ChatMessageList as children and ChatComposer as composer prop for complete chat.'},

From e1968f72437a1749c7c2b578996c0fcceffcf124 Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 8 Nov 2026 10:13:34 -0800
Subject: [PATCH 05/16] chore(changeset): name the CLI, whose browser-support
 guide changes

---
 .changeset/chat-layout-document-scroll-safari-keyboard.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.changeset/chat-layout-document-scroll-safari-keyboard.md b/.changeset/chat-layout-document-scroll-safari-keyboard.md
index a4c90a021e1ef..5900460c97ca4 100644
--- a/.changeset/chat-layout-document-scroll-safari-keyboard.md
+++ b/.changeset/chat-layout-document-scroll-safari-keyboard.md
@@ -1,5 +1,6 @@
 ---
 '@astryxdesign/core': patch
+'@astryxdesign/cli': patch
 ---
 
 [fix] **ChatLayout**: In a page that scrolls the document (`scrollRef`), the composer stays right above the software keyboard in Safari on iOS, instead of jumping under the status bar.

From 1419a71e51b48f7cbd866abb9127cef4ab145ed8 Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 8 Nov 2026 10:55:20 -0800
Subject: [PATCH 06/16] fix(ChatLayout): lift the dock unless the browser pans
 to it

Without the VirtualKeyboard API, in a page that scrolls the document,
ChatLayout now learns what the browser does at its first keyboard show.
Focus is the browser's, and the visual viewport is watched. Safari on
iOS pans to the fixed dock and keeps the pan: the dock rises nothing,
as before. A dock still covered once the visual viewport has stayed
still for 40 frames, or after 3 s, rises by the keyboard's cover. From
then on that page keeps the composer above the keyboard itself, as on
main, which Firefox for Android needs. Only a pan that reveals the dock
in that same show, before any touch or wheel, undoes that. Chrome never
takes this path.
AST-099 names the exception for Safari on iOS, with a Firefox row and a
gap for that first show.
---
 docs/specs/AST-099-mobile-keyboard/spec.md    |  34 ++-
 .../cli/assets/docs/browser-support.doc.mjs   |   2 +-
 packages/core/src/Chat/ChatLayout.doc.mjs     |   8 +-
 .../core/src/Chat/useChatKeyboard.test.tsx    | 283 +++++++++++++++++-
 packages/core/src/Chat/useChatKeyboard.ts     | 257 ++++++++++++++--
 5 files changed, 552 insertions(+), 32 deletions(-)

diff --git a/docs/specs/AST-099-mobile-keyboard/spec.md b/docs/specs/AST-099-mobile-keyboard/spec.md
index 4b47ce8d371a4..bec0591551d7a 100644
--- a/docs/specs/AST-099-mobile-keyboard/spec.md
+++ b/docs/specs/AST-099-mobile-keyboard/spec.md
@@ -101,11 +101,16 @@ app to turn on.
   or a maximum height, so layout is correct with no animation running: the chat
   composer, a search field placed at the bottom, and tab bar search position
   from it, and a fully expanded sheet extends its own scroll range by it. When
-  ChatLayout's `scrollRef` names the document's scroller, in a browser without
-  the VirtualKeyboard API, ChatLayout lifts its dock by nothing. It leaves focus
-  and the reveal to the browser there: the composer is not a keyboard-aware
-  surface (FR4). Safari on iOS pans the visual viewport to the fixed dock and
-  keeps the pan, which places the composer above the keyboard. FR9's
+  ChatLayout's `scrollRef` names the document's scroller, Safari on iOS, in the
+  browser and as a home-screen app, pans the visual viewport to the fixed dock
+  and keeps the pan. There ChatLayout leaves focus and the reveal to the
+  browser, and the dock rises nothing: the composer is not a keyboard-aware
+  surface (FR4). ChatLayout learns this from the browser's behavior. Without the
+  VirtualKeyboard API, a page's first keyboard show leaves focus to the browser
+  and watches the visual viewport. A pan to the dock marks a browser that
+  reveals it. A dock still covered once the visual viewport settles, within a
+  bounded wait (Gap 16), rises by the keyboard's cover. From then on, the
+  composer is a keyboard-aware surface there, as elsewhere. FR9's
   docked ride is the one exception: Core moves an app's docked bar as FR9 sets
   out. How the value reaches styles is `architecture:react-component-runtime`
   INV11. Riding the keyboard's motion layers on top of that layout, so layout
@@ -131,7 +136,9 @@ app to turn on.
   control into view with its own scroller. When the keyboard's Done button
   ends entry, focus moves to the surface so the next tap is handled the same
   way. A document scroll that still happens while the page is scroll-locked,
-  such as on returning to the app, is put back in the same frame.
+  such as on returning to the app, is put back in the same frame. FR3 names one
+  exception: ChatLayout's composer in Safari on iOS, when its `scrollRef` names
+  the document's scroller.
 - **FR5 — Moving a surface dismisses the keyboard.** When a surface that holds
   the focused control starts to move, such as a sheet dragged between heights,
   a drag to dismiss, or a close, the control is blurred so the keyboard
@@ -207,8 +214,8 @@ app to turn on.
     height (FR2) elsewhere, such as Safari on iOS. A Core host rides by applying
     the keyboard height on its own element (FR3), and the field inside it is not
     moved a second time. FR3 names one exception: ChatLayout's dock when its
-    `scrollRef` names the document's scroller, in a browser without the
-    VirtualKeyboard API. There the browser's reveal places it.
+    `scrollRef` names the document's scroller. In Safari on iOS, the browser's
+    own pan places it.
   - **App-owned docked containers.** A container the app owns rides too when it
     is fixed-position, does not fill the viewport, and is docked: its layout
     box, before any transform, sits at the viewport's bottom edge. A docked
@@ -383,6 +390,15 @@ No covered field meets FR9 on `main`. Each gap below is open.
   Safari on iOS (`packages/core/src/keyboard/useMobileKeyboard.ts`). But
   Firefox reports the keyboard's hide once, at its end. The sheet's content
   moves at that report, in one frame, instead of riding from the blur (FR3).
+- **Gap 16 — The first keyboard show of a document-scrolling ChatLayout without
+  the VirtualKeyboard API.** ChatLayout cannot tell before that show whether
+  the browser pans to its fixed dock (FR3). So the first show leaves focus to
+  the browser. In Firefox for Android, the first keyboard show on each page
+  leaves the composer covered for up to 40 still frames of the visual viewport.
+  That is about 0.7 s at 60 Hz, and 3 s at most. Every later show lifts the dock
+  at once. On the iOS Simulator, Safari's pan arrived 0 to 384 ms after the
+  keyboard's report. A short cover once, at Firefox's first show, is better than
+  a lift and then a drop in a slow Safari.
 
 ### Follow-up
 
@@ -406,6 +422,8 @@ that sets its own `translate`, to the app.
 | FR2–FR5  | Safari on iOS in the iOS Simulator or on a device, top-level document                                        | focus routes, keyboard shown and hidden, page panned and pinch-zoomed, a sheet moved, ChatLayout's composer, in Safari and as a home-screen app                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | The page lurches, the field ends under the keyboard, or the height is wrong after a pan or zoom                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | FR2–FR5  | Release gate: a physical iPhone in a top-level document (DEC-3)                                              | iPhone Safari with the toolbar expanded and collapsed; iPhone home-screen app; the phone's refresh rate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | The page lurches, the field ends under the keyboard, or the surface does not follow the keyboard                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | FR3–FR4  | ChatLayout's keyboard tests in jsdom and its interaction proofs in Chromium and WebKit                       | the fixed and the sticky dock with the keyboard shown and hidden; the message area's end padding; a transcript at its newest message; a page pinch-zoomed with the keyboard up; focus by tap, Tab, `focus()` and Done, under a finger and under a mouse                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | The dock left under the keyboard or lifted with none; the newest message unable to scroll above the composer; a transcript at its newest message left behind; the page panned to the composer's text under a finger, outside FR3's document-scroll exception; focus left in the text after Done, or the composer group focusable outside Done's park                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| FR3–FR4  | Firefox for Android in the emulator, top-level document                                                      | ChatLayout whose `scrollRef` names the document, the page's first keyboard show: a tap on the composer, the keyboard shown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Once the visual viewport settles, the composer does not rest on the keyboard: its bottom sits more than 0.5 CSS px below the visual viewport's bottom                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| FR3–FR4  | Firefox for Android in the emulator, top-level document                                                      | The same page's second keyboard show: a tap on the composer, the keyboard shown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | The composer does not rest on the keyboard at once: its bottom sits more than 0.5 CSS px below the visual viewport's bottom                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | FR8      | ChatLayout's interaction proofs in Chromium with Chrome's keyboard report                                    | the dock riding Gboard's slide up from the report and down from the blur; reduced motion on                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | The dock lagging Gboard's slide, laying out or painting per frame, or jumping at the hand-back; the dock travelling under reduced motion instead of DR2's cross-fade                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | FR9      | ChatLayout's keyboard tests in jsdom                                                                         | ChatComposer in the fixed and the sticky dock, above the keyboard after each focus route                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | ChatComposer ending under the keyboard, or moved a second time inside its dock, after any focus route                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | FR9      | TBD (Gap 1–11): a focus test per covered field, driving one keyboard change                                  | each covered field in the page, a Tall and a `hug` BottomSheet, ChatLayout's fixed and sticky dock, an app's fixed bar docked to the bottom edge with no `translate` of its own, and a fixed Toolbar docked there; focus by tap, Tab, and `focus()`; a field in scrolling content in the page and in a nested scroller; a field near its scroller's end; a field in a scroller inside a full-viewport fixed container                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | A focused page field or Core-host field left under the keyboard or less than 10 CSS px above it (a field with no scroller between it and a fixed container FR9 leaves to the app keeps the browser's own reveal and is not a failure; a field that a scroller holds inside such a container, left under the keyboard, is a failure), a field in an app's docked bar whose bar's bottom does not meet the keyboard's top, scroll range left at the scroller's end after the keyboard hides, a page pan or translate, a reveal later than the frame the keyboard is reported in, or a second offset inside a host that already applies the height                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
diff --git a/packages/cli/assets/docs/browser-support.doc.mjs b/packages/cli/assets/docs/browser-support.doc.mjs
index 69d9dba1d98f1..37904e3e06b92 100644
--- a/packages/cli/assets/docs/browser-support.doc.mjs
+++ b/packages/cli/assets/docs/browser-support.doc.mjs
@@ -148,7 +148,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "On a phone, the components that respond to the on-screen keyboard, a fully expanded `height='tall'` BottomSheet and ChatLayout's composer, measure it the same way: the layout viewport's height minus the visual viewport's height times its scale. Where the visual viewport shrinks for the keyboard, as in Safari on iOS in the browser and as a home-screen app, in Firefox for Android and in Chrome on Android, they keep the focused field and the surface around it above the keyboard and leave the page where it was. If Firefox for Android pans to the field, they put the page back within a couple of frames. One exception applies when ChatLayout's scrollRef names the document. Then a browser without the VirtualKeyboard API keeps the composer's focus and reveal, as Safari on iOS and Firefox for Android do.",
+          text: "On a phone, the components that respond to the on-screen keyboard, a fully expanded `height='tall'` BottomSheet and ChatLayout's composer, measure it the same way: the layout viewport's height minus the visual viewport's height times its scale. Where the visual viewport shrinks for the keyboard, as in Safari on iOS in the browser and as a home-screen app, in Firefox for Android and in Chrome on Android, they keep the focused field and the surface around it above the keyboard and leave the page where it was. If Firefox for Android pans to the field, they put the page back within a couple of frames. One exception applies when ChatLayout's scrollRef names the document. Safari on iOS then reveals the composer itself and keeps its focus. In another browser without the VirtualKeyboard API, the first keyboard show waits for the keyboard to settle before the composer rises.",
         },
         {
           type: 'prose',
diff --git a/packages/core/src/Chat/ChatLayout.doc.mjs b/packages/core/src/Chat/ChatLayout.doc.mjs
index 34b01a5cacda0..dad29319b9d29 100644
--- a/packages/core/src/Chat/ChatLayout.doc.mjs
+++ b/packages/core/src/Chat/ChatLayout.doc.mjs
@@ -6,7 +6,7 @@ export const docs = {
   name: 'ChatLayout',
   subComponentOf: 'Chat',
   displayName: 'Chat Layout',
-  description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Set density (compact/balanced/spacious) to control spacing, message max-width, and blur layer sizing. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body. Where the visual viewport shrinks for the software keyboard, the composer stays on top of the keyboard, and a conversation at its newest message stays there. In Chrome on Android the composer rides Gboard\u2019s slides in step with them. In Safari on iOS (in the browser and as a home-screen app) and in Firefox for Android, it moves above the keyboard once the browser reports it. On a touch screen, in a top-level page, every way into the composer\u2019s text (a tap, the keyboard\u2019s previous and next buttons, Tab, the input\u2019s focus()) focuses it without scrolling the page; under a mouse or inside an iframe the browser\u2019s own focus applies. When scrollRef names the document, a browser without the VirtualKeyboard API keeps focus and the composer\u2019s reveal. Safari on iOS and Firefox for Android are such browsers. Done then rests focus on no composer group. Where your page sets interactive-widget=resizes-content, Chrome on Android shrinks the page for the keyboard itself and the composer stays above it without moving (see the browser-support guide).',
+  description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Set density (compact/balanced/spacious) to control spacing, message max-width, and blur layer sizing. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body. Where the visual viewport shrinks for the software keyboard, the composer stays on top of the keyboard, and a conversation at its newest message stays there. In Chrome on Android the composer rides Gboard\u2019s slides in step with them. In Safari on iOS (in the browser and as a home-screen app) and in Firefox for Android, it moves above the keyboard once the browser reports it. On a touch screen, in a top-level page, every way into the composer\u2019s text (a tap, the keyboard\u2019s previous and next buttons, Tab, the input\u2019s focus()) focuses it without scrolling the page; under a mouse or inside an iframe the browser\u2019s own focus applies. When scrollRef names the document, Safari on iOS reveals the composer itself, in the browser and as a home-screen app. Done then rests focus on no composer group. In another browser without the VirtualKeyboard API, the first keyboard show keeps the browser\u2019s focus, and the composer rises once the keyboard settles. Later shows work as elsewhere. Where your page sets interactive-widget=resizes-content, Chrome on Android shrinks the page for the keyboard itself and the composer stays above it without moving (see the browser-support guide).',
   props: [
     {
       name: 'children',
@@ -107,7 +107,7 @@ export const docs = {
       {
         name: 'Composer',
         required: true,
-        description: 'The input area for sending messages, typically ChatComposer. Docked at the bottom inside the frosted glass layer. In a top-level page on a touch screen, its wrapper (without the scroll button) is a group with no name. When the keyboard\u2019s Done ends typing, focus rests on that group (it is no tab stop), so the next tap or Tab starts from the composer. It shows the focus ring after keyboard input only. Under a mouse or inside an iframe, the wrapper is a plain container. So it is when scrollRef names the document in a browser without the VirtualKeyboard API: the browser keeps focus there.',
+        description: 'The input area for sending messages, typically ChatComposer. Docked at the bottom inside the frosted glass layer. In a top-level page on a touch screen, its wrapper (without the scroll button) is a group with no name. When the keyboard\u2019s Done ends typing, focus rests on that group (it is no tab stop), so the next tap or Tab starts from the composer. It shows the focus ring after keyboard input only. Under a mouse or inside an iframe, the wrapper is a plain container. So it is when scrollRef names the document in Safari on iOS: the browser keeps focus there.',
       },
       {
         name: 'Empty state',
@@ -121,7 +121,7 @@ export const docs = {
 export const docsZh = {
   name: 'ChatLayout',
   displayName: 'Chat Layout',
-  description: '完整聊天界面的布局外壳。消息在页面中自然流动，编写器固定在底部，带有毛玻璃效果。通过 density 属性控制密度。在可视视口会随软键盘缩小的浏览器中，编写器停在键盘上方，停留在最新消息的对话保持在最新消息。在 Android 上的 Chrome 中，编写器随 Gboard 的滑动同步移动。在 iOS 上的 Safari（浏览器中和添加到主屏幕的网页应用）和 Android 上的 Firefox 中，编写器会在浏览器报告键盘后移到键盘上方。在触摸屏上的顶层页面中，进入编写器文本的每种方式（轻点、键盘的上一项和下一项按钮、Tab、输入框的 focus()）都会聚焦它而不滚动页面；使用鼠标或在 iframe 中时沿用浏览器自身的聚焦行为。当 scrollRef 指向文档，且浏览器没有 VirtualKeyboard API（iOS 上的 Safari、Android 上的 Firefox）时，ChatLayout 把聚焦和编写器的显示交给浏览器，键盘的“完成”也不会把焦点停在编写器分组上。如果页面设置了 interactive-widget=resizes-content，Android 上的 Chrome 会自行为键盘缩小页面，编写器停在键盘上方而不移动（参见浏览器支持指南）。',
+  description: '完整聊天界面的布局外壳。消息在页面中自然流动，编写器固定在底部，带有毛玻璃效果。通过 density 属性控制密度。在可视视口会随软键盘缩小的浏览器中，编写器停在键盘上方，停留在最新消息的对话保持在最新消息。在 Android 上的 Chrome 中，编写器随 Gboard 的滑动同步移动。在 iOS 上的 Safari（浏览器中和添加到主屏幕的网页应用）和 Android 上的 Firefox 中，编写器会在浏览器报告键盘后移到键盘上方。在触摸屏上的顶层页面中，进入编写器文本的每种方式（轻点、键盘的上一项和下一项按钮、Tab、输入框的 focus()）都会聚焦它而不滚动页面；使用鼠标或在 iframe 中时沿用浏览器自身的聚焦行为。当 scrollRef 指向文档时，iOS 上的 Safari（浏览器中和主屏幕网页应用）会自行将编写器显示在键盘上方，键盘的“完成”也不会把焦点停在编写器分组上。在其他没有 VirtualKeyboard API 的浏览器中，第一次弹出键盘时沿用浏览器自身的聚焦，编写器会在键盘稳定后升到键盘上方；之后的弹出与其他情况相同。如果页面设置了 interactive-widget=resizes-content，Android 上的 Chrome 会自行为键盘缩小页面，编写器停在键盘上方而不移动（参见浏览器支持指南）。',
   propDescriptions: {
     children: '消息内容，通常是 ChatMessageList。在页面中自然流动。',
     composer: '编写器元素，通常是 ChatComposer。固定在底部，带有毛玻璃底座。',
@@ -135,7 +135,7 @@ export const docsZh = {
 export const docsDense = {
   name: 'ChatLayout',
   displayName: 'Chat Layout',
-  description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; density prop (default balanced); scrollRef delegates to parent/body; in Chrome on Android (Gboard) the composer rides the software keyboard in step; in Safari on iOS and Firefox for Android it moves above the keyboard once reported (Chrome with interactive-widget=resizes-content: the page resizes, no move); transcript stays at newest msg, on a touch screen in a top-level page every focus route (tap, prev/next, Tab, focus()) w/o page scroll and Done rests focus on the composer group (no name, ring after keyboard input only, no tab stop); under a mouse or in an iframe: plain wrapper, browser focus; scrollRef on the document without the VirtualKeyboard API (Safari on iOS, Firefox for Android): browser focus and reveal, no group',
+  description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; density prop (default balanced); scrollRef delegates to parent/body; in Chrome on Android (Gboard) the composer rides the software keyboard in step; in Safari on iOS and Firefox for Android it moves above the keyboard once reported (Chrome with interactive-widget=resizes-content: the page resizes, no move); transcript stays at newest msg, on a touch screen in a top-level page every focus route (tap, prev/next, Tab, focus()) w/o page scroll and Done rests focus on the composer group (no name, ring after keyboard input only, no tab stop); under a mouse or in an iframe: plain wrapper, browser focus; scrollRef on the document in Safari on iOS: Safari reveals the composer, browser focus, no group; other browsers without the VirtualKeyboard API: the first keyboard show rises once settled',
   usage: {
     bestPractices: [
       {guidance: true, description: 'Pass ChatMessageList as children and ChatComposer as composer prop for complete chat.'},
diff --git a/packages/core/src/Chat/useChatKeyboard.test.tsx b/packages/core/src/Chat/useChatKeyboard.test.tsx
index 1d49198e4fb37..f9462e2c9db4e 100644
--- a/packages/core/src/Chat/useChatKeyboard.test.tsx
+++ b/packages/core/src/Chat/useChatKeyboard.test.tsx
@@ -18,7 +18,13 @@ import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
 import {act, fireEvent, render, screen} from '@testing-library/react';
 import {ChatComposer} from './ChatComposer';
 import {ChatLayout} from './ChatLayout';
-import {editableToClaim} from './useChatKeyboard';
+import {
+  __leavesRevealToBrowserForTest,
+  __learnRevealForTest,
+  __resetRevealForTest,
+  __revealLearnedForTest,
+  editableToClaim,
+} from './useChatKeyboard';
 import {getKeyboardLayoutGuide} from '../keyboard/keyboardLayoutGuide';
 import {__resetInteractionModalityForTest} from '../utils/interactionModality';
 import {__focusTakeoverCallersForTest} from '../keyboard/keyboardHeight';
@@ -366,14 +372,60 @@ describe('ChatLayout in a page that scrolls the document', () => {
       configurable: true,
       value: viewport,
     });
+    __resetRevealForTest(window);
   });
 
   afterEach(() => {
     Reflect.deleteProperty(window, 'visualViewport');
     Reflect.deleteProperty(navigator, 'virtualKeyboard');
     vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+    __resetRevealForTest(window);
   });
 
+  // Scripted animation frames: the wait for the browser's pan counts frames,
+  // so these cases run no clock.
+  let frames = new Map<number, FrameRequestCallback>();
+  function scriptFrames() {
+    frames = new Map();
+    let nextFrame = 1;
+    vi.spyOn(window, 'requestAnimationFrame').mockImplementation(callback => {
+      const id = nextFrame;
+      nextFrame += 1;
+      frames.set(id, callback);
+      return id;
+    });
+    vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(id => {
+      frames.delete(id);
+    });
+  }
+  function frame(count = 1) {
+    act(() => {
+      for (let i = 0; i < count; i += 1) {
+        const queued = [...frames.values()];
+        frames.clear();
+        for (const callback of queued) {
+          callback(performance.now());
+        }
+      }
+    });
+  }
+  // A finger down on the page, or none.
+  function touches(count: number) {
+    const event = new Event(count > 0 ? 'touchstart' : 'touchend');
+    Object.defineProperty(event, 'touches', {value: {length: count}});
+    act(() => {
+      document.dispatchEvent(event);
+    });
+  }
+  // The browser pans the visual viewport, as Safari's reveal of the dock does.
+  function pan(offsetTop: number) {
+    viewport.offsetTop = offsetTop;
+    act(() => {
+      viewport.dispatchEvent(new Event('scroll'));
+    });
+  }
+
   function renderDocumentLayout() {
     return render(
       <ChatLayout
@@ -399,6 +451,229 @@ describe('ChatLayout in a page that scrolls the document', () => {
     expect(keyboardRoom(messagesOf())).toBe(0);
   });
 
+  it('lifts the fixed dock by the keyboard once the visual viewport settles with no pan, as in Firefox for Android', () => {
+    scriptFrames();
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    frame(10);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    frame(40);
+    expect(layoutLift(dockOf(container))).toBe(290);
+    expect(keyboardRoom(messagesOf())).toBe(290);
+    expect(__revealLearnedForTest(window)).toBe(false);
+  });
+
+  it('lifts nothing when the visual viewport pans within the wait, as Safari on iOS does', () => {
+    scriptFrames();
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 337);
+    frame(20);
+    pan(337);
+    frame(60);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    expect(keyboardRoom(messagesOf())).toBe(0);
+    expect(__revealLearnedForTest(window)).toBe(true);
+    expect(__focusTakeoverCallersForTest(document)).toBe(0);
+  });
+
+  it('lifts nothing when the dock is already revealed at the report, and learns nothing from a show that needed no pan', () => {
+    scriptFrames();
+    viewport.offsetTop = 337;
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 337);
+    frame(60);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    expect(__revealLearnedForTest(window)).toBeUndefined();
+  });
+
+  it('drops the lift once when the browser pans after the wait, and keeps it off for that show', () => {
+    scriptFrames();
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    frame(45);
+    expect(layoutLift(dockOf(container))).toBe(290);
+    pan(290);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    pan(0);
+    frame(45);
+    expect(layoutLift(dockOf(container))).toBe(0);
+  });
+
+  it('after a show that left the dock covered, keeps the composer above the keyboard itself: the takeover, and a lift with no wait', () => {
+    scriptFrames();
+    const {container} = renderDocumentLayout();
+    expect(__focusTakeoverCallersForTest(document)).toBe(0);
+    report(window.innerHeight - 290);
+    frame(45);
+    expect(__focusTakeoverCallersForTest(document)).toBe(1);
+    report(window.innerHeight);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    report(window.innerHeight - 290);
+    expect(layoutLift(dockOf(container))).toBe(290);
+  });
+
+  it('keeps the lift when a finger pans the visual viewport with the keyboard up, as a reader\u2019s scroll in Firefox does', () => {
+    scriptFrames();
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    frame(45);
+    expect(layoutLift(dockOf(container))).toBe(290);
+    touches(1);
+    pan(156.4);
+    frame(5);
+    pan(290);
+    frame(5);
+    expect(layoutLift(dockOf(container))).toBe(290);
+    expect(__revealLearnedForTest(window)).toBe(false);
+  });
+
+  it('keeps the lift for a small pan with no finger down', () => {
+    scriptFrames();
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    frame(45);
+    pan(40);
+    frame(5);
+    expect(layoutLift(dockOf(container))).toBe(290);
+  });
+
+  it('drops the lift once for a slow browser whose pan to the dock comes after the settle, and leaves it the reveal', () => {
+    scriptFrames();
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 337);
+    frame(45);
+    expect(layoutLift(dockOf(container))).toBe(337);
+    pan(337);
+    frame(2);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    expect(__revealLearnedForTest(window)).toBe(true);
+    expect(__focusTakeoverCallersForTest(document)).toBe(0);
+  });
+
+  it('keeps the lift for a reveal-sized pan after a touch, as a reader\u2019s fling to the end', () => {
+    scriptFrames();
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    frame(45);
+    expect(layoutLift(dockOf(container))).toBe(290);
+    touches(1);
+    touches(0);
+    pan(290);
+    frame(2);
+    expect(layoutLift(dockOf(container))).toBe(290);
+    expect(__revealLearnedForTest(window)).toBe(false);
+  });
+
+  it('keeps the lift for a reveal-sized pan after a wheel', () => {
+    scriptFrames();
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    frame(45);
+    act(() => {
+      document.dispatchEvent(new Event('wheel'));
+    });
+    pan(290);
+    frame(2);
+    expect(layoutLift(dockOf(container))).toBe(290);
+  });
+
+  it('keeps the lift on a show that reached the cap when a touch came before the pan', () => {
+    scriptFrames();
+    let now = 1000;
+    vi.spyOn(performance, 'now').mockImplementation(() => now);
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    // The visual viewport never settles: the cap decides, and nothing is learned.
+    for (let i = 0; i < 31; i += 1) {
+      now += 100;
+      viewport.height = window.innerHeight - 290 - (i % 2);
+      frame();
+    }
+    expect(layoutLift(dockOf(container))).toBe(290);
+    expect(__revealLearnedForTest(window)).toBeUndefined();
+    touches(1);
+    touches(0);
+    pan(290);
+    frame(2);
+    expect(layoutLift(dockOf(container))).toBe(290);
+  });
+
+  it('never flips a page that learned the dock stays covered at a later show', () => {
+    scriptFrames();
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    frame(45);
+    report(window.innerHeight);
+    report(window.innerHeight - 290);
+    expect(layoutLift(dockOf(container))).toBe(290);
+    pan(290);
+    frame(2);
+    expect(layoutLift(dockOf(container))).toBe(290);
+    expect(__revealLearnedForTest(window)).toBe(false);
+  });
+
+  it('restarts the count, but decides nothing, for a pan during the wait that is smaller than the cover', () => {
+    scriptFrames();
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    frame(10);
+    pan(40);
+    frame(30);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    frame(15);
+    expect(layoutLift(dockOf(container))).toBe(290);
+  });
+
+  it('after a show the browser panned to, keeps leaving the reveal to it', () => {
+    scriptFrames();
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 337);
+    frame(5);
+    pan(337);
+    frame(2);
+    report(window.innerHeight);
+    pan(0);
+    report(window.innerHeight - 337);
+    frame(3);
+    pan(337);
+    frame(60);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    expect(__focusTakeoverCallersForTest(document)).toBe(0);
+    expect(__revealLearnedForTest(window)).toBe(true);
+  });
+
+  it('learns per window: what one page found never changes another', () => {
+    const root = document.documentElement;
+    const first = {navigator: {}} as unknown as Window;
+    const second = {navigator: {}} as unknown as Window;
+    __learnRevealForTest(first, false);
+    expect(__leavesRevealToBrowserForTest(first, root)).toBe(false);
+    expect(__leavesRevealToBrowserForTest(second, root)).toBe(true);
+    __learnRevealForTest(second, true);
+    expect(__leavesRevealToBrowserForTest(second, root)).toBe(true);
+    expect(__revealLearnedForTest(first)).toBe(false);
+    __resetRevealForTest(first);
+    __resetRevealForTest(second);
+  });
+
+  it('counts frames, not time: a busy device that draws few frames waits longer, up to a cap', () => {
+    scriptFrames();
+    let now = 1000;
+    vi.spyOn(performance, 'now').mockImplementation(() => now);
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    for (let i = 0; i < 20; i += 1) {
+      now += 100;
+      frame();
+    }
+    expect(layoutLift(dockOf(container))).toBe(0);
+    for (let i = 0; i < 10; i += 1) {
+      now += 100;
+      frame();
+    }
+    expect(layoutLift(dockOf(container))).toBe(290);
+  });
+
   it('leaves the composer\u2019s focus to Safari there: no focus takeover and no composer group', () => {
     renderDocumentLayout();
     const region = screen.getByTestId('composer').parentElement!.parentElement!;
@@ -437,10 +712,16 @@ describe('ChatLayout in a page that scrolls the document', () => {
       value: {overlaysContent: false},
     });
     const {container} = renderDocumentLayout();
+    expect(
+      __leavesRevealToBrowserForTest(window, document.documentElement),
+    ).toBe(false);
     report(window.innerHeight - 300);
     await settle();
     expect(layoutLift(dockOf(container))).toBe(300);
     expect(keyboardRoom(messagesOf())).toBe(300);
+    // The reveal wait never runs where the layout guide rides the keyboard.
+    expect(__revealLearnedForTest(window)).toBeUndefined();
+    expect(__focusTakeoverCallersForTest(document)).toBe(1);
   });
 });
 
diff --git a/packages/core/src/Chat/useChatKeyboard.ts b/packages/core/src/Chat/useChatKeyboard.ts
index e473ea12aab1d..8457665c5455e 100644
--- a/packages/core/src/Chat/useChatKeyboard.ts
+++ b/packages/core/src/Chat/useChatKeyboard.ts
@@ -6,7 +6,7 @@
  * @file useChatKeyboard.ts
  * @input React refs, the keyboard module's height, focus routes and layout
  *   guide, the stream scroll's lock, the motion engine, the touch query and
- *   layout viewport height
+ *   layout viewport height. Also the input stream's touches and wheels
  * @output Exports useChatKeyboard: the lift for ChatLayout's dock and message
  *   area, and the refs for its dock, message area and composer region. It
  *   also tells whether a focus call in the composer skips the browser's reveal
@@ -46,6 +46,7 @@ import {
 import type {KeyboardTransition} from '../keyboard/keyboardModel';
 import {rideKeyboard} from '../keyboard/rideKeyboard';
 import {layoutViewportHeight} from '../utils/layoutViewport';
+import {subscribeInput} from '../utils/inputStream';
 import {useInteractionModalityTrackingFor} from '../utils/interactionModality';
 import {isCoarsePointer} from '../utils/coarsePointer';
 import {useTouchPresentation} from '../utils/touchPresentation';
@@ -207,6 +208,17 @@ export function useChatKeyboard({
     liftStore.get,
   );
   const liftRef = useRef(0);
+  // Whether this keyboard show is the one that found the dock covered, and
+  // whether a touch or a wheel came since its report. Only that show, with no
+  // input yet, can still meet a slow browser's own pan to the dock.
+  const classifyingShowRef = useRef(false);
+  const inputSinceReportRef = useRef(false);
+  // What this window's browser did at a keyboard show, for the effects below.
+  const revealVersion = useSyncExternalStore(
+    subscribeReveal,
+    readRevealVersion,
+    readRevealVersion,
+  );
   // Set while the guide's ride is under way: the layout waits for it. Each
   // ride's number, so only the latest one hands its translate back.
   const ridingRef = useRef(false);
@@ -232,14 +244,116 @@ export function useChatKeyboard({
     if (root == null || win == null) {
       return undefined;
     }
+    // Where the browser keeps focus and the composer's reveal, each keyboard
+    // show decides once whether the dock rises. A browser that pans the
+    // visual viewport to the fixed dock reveals it: the dock rises nothing,
+    // so a lift never adds to the pan. A dock still covered once the visual
+    // viewport has settled rises by the keyboard's cover, as elsewhere.
+    const unguidedDocument =
+      isDocumentScroller(scrollRef.current) &&
+      keyboardProfileOf(win) !== 'chromium';
+    const leavesReveal = leavesRevealToBrowser(win, scrollRef.current);
+    // The fingers down on the page. A pan under a finger is the reader's, not
+    // the browser's reveal.
+    let touchesDown = 0;
+    const onInput = (event: Event) => {
+      if (event.type !== 'wheel') {
+        touchesDown = (event as TouchEvent).touches?.length ?? 0;
+      }
+      if (event.type === 'touchstart' || event.type === 'wheel') {
+        inputSinceReportRef.current = true;
+      }
+    };
+    const stopInput = unguidedDocument
+      ? (['touchstart', 'touchend', 'touchcancel', 'wheel'] as const).map(
+          type => subscribeInput(win, type, onInput),
+        )
+      : [];
+    // A pan that reveals the fixed dock, with no finger down: with no lift,
+    // the dock would rest at or above the visual viewport's bottom.
+    const isRevealPan = (pan: number | null, inset: number) =>
+      pan != null && inset > 0 && touchesDown === 0 && pan >= inset - 1;
+    let reveal: 'none' | 'watching' | 'revealed' | 'covered' = 'none';
+    let revealFrame = 0;
+    let coveredAt = 0;
+    // The visual viewport's pan with no keyboard up: a show's pan is measured
+    // from it.
+    let restPan = 0;
+    // The visual viewport's pan, or null under a pinch zoom, whose pan is the
+    // reader's.
+    const panOf = () => {
+      const viewport = win.visualViewport;
+      return viewport != null && viewport.scale === 1
+        ? viewport.offsetTop
+        : null;
+    };
+    const stopWatching = () => {
+      if (revealFrame !== 0) {
+        win.cancelAnimationFrame(revealFrame);
+        revealFrame = 0;
+      }
+    };
+    const watchReveal = () => {
+      stopWatching();
+      const startPan = panOf();
+      if (startPan != null && startPan >= getKeyboardHeight(win) - 1) {
+        // Revealed at the report. Only a pan there shows what the browser
+        // does; a show that needed none teaches nothing.
+        reveal = 'revealed';
+        if (startPan > restPan + 0.5) {
+          learnReveal(win, true);
+        }
+        return;
+      }
+      reveal = 'watching';
+      const start = win.performance.now();
+      let height = win.visualViewport?.height;
+      let lastPan = startPan;
+      let stillFrames = 0;
+      const step = () => {
+        revealFrame = 0;
+        const pan = panOf();
+        const inset = getKeyboardHeight(win);
+        if (inset <= 0) {
+          reveal = 'none';
+          return;
+        }
+        // A pan that reveals the dock is the browser's reveal. A smaller one,
+        // or one under a finger, only restarts the count.
+        if (isRevealPan(pan, inset) && pan != null && pan > restPan + 0.5) {
+          reveal = 'revealed';
+          learnReveal(win, true);
+          return;
+        }
+        const nextHeight = win.visualViewport?.height;
+        const isStill = nextHeight === height && pan === lastPan;
+        stillFrames = isStill ? stillFrames + 1 : 0;
+        height = nextHeight;
+        lastPan = pan;
+        const settled = stillFrames >= REVEAL_SETTLE_FRAMES;
+        if (settled || win.performance.now() - start >= REVEAL_WAIT_CAP_MS) {
+          reveal = 'covered';
+          coveredAt = win.visualViewport?.offsetTop ?? 0;
+          commit();
+          // A dock still covered on a still visual viewport: this browser
+          // reveals no fixed dock. From the next render on, the layout keeps
+          // the composer above the keyboard itself, with no wait.
+          if (settled) {
+            classifyingShowRef.current = true;
+            learnReveal(win, false);
+          }
+          return;
+        }
+        revealFrame = win.requestAnimationFrame(step);
+      };
+      revealFrame = win.requestAnimationFrame(step);
+    };
     // A sticky dock rests at the root's bottom edge, which may sit above or
     // below the layout viewport's; a fixed dock rests at the viewport's.
     // While a keyboard is up the dock rises until it clears the keyboard's
-    // cover; without one it rests where the layout puts it. Where the browser
-    // reveals the composer itself, the dock rises nothing.
-    const leavesReveal = leavesRevealToBrowser(win, scrollRef.current);
+    // cover; without one it rests where the layout puts it.
     const liftFor = (inset: number) => {
-      if (inset <= 0 || leavesReveal) {
+      if (inset <= 0 || (leavesReveal && reveal !== 'covered')) {
         return 0;
       }
       // In layout px, as the root's rect is, under a pinch zoom too.
@@ -341,16 +455,67 @@ export function useChatKeyboard({
     // so a ride claims the change first.
     let reportedHeight = getKeyboardHeight(win);
     const unsubscribeHeight = subscribeKeyboardHeight(win, event => {
-      if (event.type === 'viewport' && event.height !== reportedHeight) {
+      if (event.type !== 'viewport') {
+        return;
+      }
+      if (event.height > 0 && reportedHeight <= 0) {
+        inputSinceReportRef.current = false;
+      } else if (event.height <= 0) {
+        classifyingShowRef.current = false;
+      }
+      if (leavesReveal) {
+        const viewport = win.visualViewport;
+        if (event.height <= 0) {
+          stopWatching();
+          reveal = 'none';
+          restPan = panOf() ?? 0;
+        } else if (reveal === 'none') {
+          watchReveal();
+        } else if (
+          reveal === 'covered' &&
+          viewport != null &&
+          viewport.scale === 1 &&
+          viewport.offsetTop > coveredAt + 0.5 &&
+          !inputSinceReportRef.current &&
+          isRevealPan(viewport.offsetTop, event.height)
+        ) {
+          // The browser panned to the dock after the wait: the lift goes, and
+          // it does not come back in this show.
+          reveal = 'revealed';
+          learnReveal(win, true);
+          commit();
+        }
+      } else if (
+        unguidedDocument &&
+        liftRef.current > 0 &&
+        classifyingShowRef.current &&
+        !inputSinceReportRef.current &&
+        isRevealPan(panOf(), event.height)
+      ) {
+        // A slow browser panned to the dock after the show that found it
+        // covered, before any input. The lift goes once, and the browser
+        // keeps the reveal. A pan after a touch or a wheel is the reader's.
+        learnReveal(win, true);
+      }
+      if (event.height !== reportedHeight) {
         reportedHeight = event.height;
         commit();
       }
     });
     // Mounted under a keyboard that is already up: take its place at once.
+    if (leavesReveal && reportedHeight > 0) {
+      watchReveal();
+    } else {
+      restPan = panOf() ?? 0;
+    }
     commit();
     return () => {
       unsubscribeHeight();
       unsubscribe?.();
+      stopWatching();
+      for (const stop of stopInput) {
+        stop();
+      }
       ridingRef.current = false;
     };
   }, [
@@ -361,6 +526,7 @@ export function useChatKeyboard({
     dock.animator,
     messages.animator,
     liftStore,
+    revealVersion,
   ]);
 
   // Synchronizes the dock's and the transcript's translates, and the
@@ -424,7 +590,7 @@ export function useChatKeyboard({
       claim: editableToClaim,
       deliver: deliverTap,
     });
-  }, [touchPresentation.isTouch, scrollRef]);
+  }, [touchPresentation.isTouch, scrollRef, revealVersion]);
 
   // A browser that reveals the composer itself pans the visual viewport after
   // the keyboard's report, while the composer still rides up. Chrome 124 on
@@ -452,7 +618,7 @@ export function useChatKeyboard({
       unsubscribe();
       pans.stop();
     };
-  }, [touchPresentation.isTouch, scrollRef]);
+  }, [touchPresentation.isTouch, scrollRef, revealVersion]);
 
   // Synchronizes the keyboard module's focus takeover, and the region's group
   // role, with the touch presentation. Every other move into the composer's
@@ -488,7 +654,7 @@ export function useChatKeyboard({
       stopTakeover();
       composer.removeAttribute('role');
     };
-  }, [touchPresentation.isTouch, readModality, scrollRef]);
+  }, [touchPresentation.isTouch, readModality, scrollRef, revealVersion]);
 
   // A focus call skips the browser's reveal only where ChatLayout keeps the
   // composer above the keyboard itself. The server has no keyboard profile.
@@ -498,7 +664,7 @@ export function useChatKeyboard({
     return win == null || !leavesRevealToBrowser(win, scroller);
   }, [scrollRef]);
   const isKeyboardSurface = useSyncExternalStore(
-    subscribeToNothing,
+    subscribeReveal,
     readKeyboardSurface,
     readKeyboardSurfaceOnServer,
   );
@@ -512,19 +678,74 @@ export function useChatKeyboard({
   };
 }
 
-// A browser's keyboard profile never changes while the page runs.
-const subscribeToNothing = () => () => {};
+// How long a keyboard show waits for the browser's own pan to the dock. The
+// visual viewport must stay still for these frames, with a cap in wall time.
+// A busy device draws fewer frames, so it waits longer. Safari on iOS pans up
+// to about 400 ms after the keyboard's report.
+const REVEAL_SETTLE_FRAMES = 40;
+const REVEAL_WAIT_CAP_MS = 3000;
+
 const readKeyboardSurfaceOnServer = () => true;
 
+// What each window's browser did with a fixed dock at a keyboard show. True:
+// it panned the visual viewport to reveal the dock. False: the dock stayed
+// covered. Unknown until the first show.
+const revealLearned = new WeakMap<Window, boolean>();
+const revealListeners = new Set<() => void>();
+let revealVersionNow = 0;
+function learnReveal(win: Window, pans: boolean): void {
+  if (revealLearned.get(win) === pans) {
+    return;
+  }
+  revealLearned.set(win, pans);
+  revealVersionNow += 1;
+  for (const listener of revealListeners) {
+    listener();
+  }
+}
+function subscribeReveal(listener: () => void): () => void {
+  revealListeners.add(listener);
+  return () => {
+    revealListeners.delete(listener);
+  };
+}
+const readRevealVersion = () => revealVersionNow;
+
+/** What `win`'s browser was found to do with a fixed dock (tests only). */
+export function __revealLearnedForTest(win: Window): boolean | undefined {
+  return revealLearned.get(win);
+}
+
+/** Forgets what `win`'s browser was found to do (tests only). */
+export function __resetRevealForTest(win: Window): void {
+  if (revealLearned.delete(win)) {
+    revealVersionNow += 1;
+    for (const listener of revealListeners) {
+      listener();
+    }
+  }
+}
+
+/** Records what `win`'s browser did with a fixed dock (tests only). */
+export const __learnRevealForTest = learnReveal;
+
+/** Whether ChatLayout leaves the composer's reveal to `win` (tests only). */
+export const __leavesRevealToBrowserForTest = leavesRevealToBrowser;
+
 /**
- * Whether the browser keeps the composer above the keyboard itself. That is a
- * page that scrolls the document, in a browser with no layout guide, such as
- * Safari on iOS. Safari pans the visual viewport to the fixed dock and keeps
- * the pan. A lift would add to that pan. So ChatLayout leaves focus, the
- * reveal and the dock's place to the browser there.
+ * Whether the browser keeps focus and the composer's reveal. That is a page
+ * that scrolls the document, in a browser with no layout guide. It holds
+ * until a keyboard show finds the fixed dock left covered. Safari on iOS pans
+ * the visual viewport to the dock, and a lift would add to that pan. Firefox
+ * for Android leaves it covered: from then on, the layout keeps the composer
+ * above the keyboard itself.
  */
 function leavesRevealToBrowser(win: Window, scroller: Element | null): boolean {
-  return isDocumentScroller(scroller) && keyboardProfileOf(win) !== 'chromium';
+  return (
+    isDocumentScroller(scroller) &&
+    keyboardProfileOf(win) !== 'chromium' &&
+    revealLearned.get(win) !== false
+  );
 }
 
 // The document's root and body both scroll the page.

From e391719bba568f7ea3b20a44500be8cb1c58d684 Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 8 Nov 2026 12:33:32 -0800
Subject: [PATCH 07/16] fix(ChatLayout): the keyboard module watches the dock's
 reveal

The reveal watch moves into the keyboard module as an opt-in
`dock` option of watchRevealPan and watchPans, off by default.
It reads the pan the module takes with each report, and decides
each show on a timer from the show's opening report. Only a pan
restarts that timer; the height reports of the keyboard's slide
do not. A touch or a wheel since the opening report closes the
late-pan check for the whole show.

Tests pin each gate: the tap claim, the focus() reveal and the
put-back, before and after a page learns the dock is covered.
FR4 and the composer prop name the first-show case.
---
 ...-layout-document-scroll-safari-keyboard.md |   2 +-
 docs/specs/AST-099-mobile-keyboard/spec.md    |  23 +-
 packages/core/src/Chat/ChatLayout.doc.mjs     |   2 +-
 .../core/src/Chat/useChatKeyboard.test.tsx    | 446 ++++++++++--------
 packages/core/src/Chat/useChatKeyboard.ts     | 268 ++---------
 packages/core/src/keyboard/README.md          |  10 +-
 .../core/src/keyboard/keyboardHeight.test.ts  |  66 +++
 packages/core/src/keyboard/keyboardHeight.ts  | 293 +++++++++++-
 packages/core/src/keyboard/keyboardTarget.ts  |  18 +-
 9 files changed, 676 insertions(+), 452 deletions(-)

diff --git a/.changeset/chat-layout-document-scroll-safari-keyboard.md b/.changeset/chat-layout-document-scroll-safari-keyboard.md
index 5900460c97ca4..b943d7d3626eb 100644
--- a/.changeset/chat-layout-document-scroll-safari-keyboard.md
+++ b/.changeset/chat-layout-document-scroll-safari-keyboard.md
@@ -3,5 +3,5 @@
 '@astryxdesign/cli': patch
 ---
 
-[fix] **ChatLayout**: In a page that scrolls the document (`scrollRef`), the composer stays right above the software keyboard in Safari on iOS, instead of jumping under the status bar.
+[fix] **ChatLayout**: In a page that scrolls the document (`scrollRef`), the composer stays right above the software keyboard in Safari on iOS, instead of jumping under the status bar. In Firefox for Android, the first keyboard show on each page covers the composer for up to about 0.7 s before it rises.
 @vjeux
diff --git a/docs/specs/AST-099-mobile-keyboard/spec.md b/docs/specs/AST-099-mobile-keyboard/spec.md
index bec0591551d7a..02e9738707c88 100644
--- a/docs/specs/AST-099-mobile-keyboard/spec.md
+++ b/docs/specs/AST-099-mobile-keyboard/spec.md
@@ -136,9 +136,10 @@ app to turn on.
   control into view with its own scroller. When the keyboard's Done button
   ends entry, focus moves to the surface so the next tap is handled the same
   way. A document scroll that still happens while the page is scroll-locked,
-  such as on returning to the app, is put back in the same frame. FR3 names one
-  exception: ChatLayout's composer in Safari on iOS, when its `scrollRef` names
-  the document's scroller.
+  such as on returning to the app, is put back in the same frame. FR3 names two
+  exceptions when ChatLayout's `scrollRef` names the document's scroller: its
+  composer in Safari on iOS, and a page's first keyboard show in another browser
+  without the VirtualKeyboard API (Gap 16).
 - **FR5 — Moving a surface dismisses the keyboard.** When a surface that holds
   the focused control starts to move, such as a sheet dragged between heights,
   a drag to dismiss, or a close, the control is blurred so the keyboard
@@ -391,14 +392,14 @@ No covered field meets FR9 on `main`. Each gap below is open.
   Firefox reports the keyboard's hide once, at its end. The sheet's content
   moves at that report, in one frame, instead of riding from the blur (FR3).
 - **Gap 16 — The first keyboard show of a document-scrolling ChatLayout without
-  the VirtualKeyboard API.** ChatLayout cannot tell before that show whether
-  the browser pans to its fixed dock (FR3). So the first show leaves focus to
-  the browser. In Firefox for Android, the first keyboard show on each page
-  leaves the composer covered for up to 40 still frames of the visual viewport.
-  That is about 0.7 s at 60 Hz, and 3 s at most. Every later show lifts the dock
-  at once. On the iOS Simulator, Safari's pan arrived 0 to 384 ms after the
-  keyboard's report. A short cover once, at Firefox's first show, is better than
-  a lift and then a drop in a slow Safari.
+  the VirtualKeyboard API.** ChatLayout cannot tell before that show whether the
+  browser pans to its fixed dock (FR3). So the first show leaves focus to the
+  browser. In Firefox for Android, the first keyboard show on each page leaves
+  the composer covered for about 0.7 s after the keyboard's report. Only a pan
+  of the visual viewport restarts that wait, and the wait ends at 3 s at most.
+  Every later show lifts the dock at once. On the iOS Simulator, Safari's pan
+  arrived 0 to 384 ms after the keyboard's report. A short cover once, at
+  Firefox's first show, is better than a lift and then a drop in a slow Safari.
 
 ### Follow-up
 
diff --git a/packages/core/src/Chat/ChatLayout.doc.mjs b/packages/core/src/Chat/ChatLayout.doc.mjs
index dad29319b9d29..4d707e416ca7f 100644
--- a/packages/core/src/Chat/ChatLayout.doc.mjs
+++ b/packages/core/src/Chat/ChatLayout.doc.mjs
@@ -107,7 +107,7 @@ export const docs = {
       {
         name: 'Composer',
         required: true,
-        description: 'The input area for sending messages, typically ChatComposer. Docked at the bottom inside the frosted glass layer. In a top-level page on a touch screen, its wrapper (without the scroll button) is a group with no name. When the keyboard\u2019s Done ends typing, focus rests on that group (it is no tab stop), so the next tap or Tab starts from the composer. It shows the focus ring after keyboard input only. Under a mouse or inside an iframe, the wrapper is a plain container. So it is when scrollRef names the document in Safari on iOS: the browser keeps focus there.',
+        description: 'The input area for sending messages, typically ChatComposer. Docked at the bottom inside the frosted glass layer. In a top-level page on a touch screen, its wrapper (without the scroll button) is a group with no name. When the keyboard\u2019s Done ends typing, focus rests on that group (it is no tab stop), so the next tap or Tab starts from the composer. It shows the focus ring after keyboard input only. Under a mouse or inside an iframe, the wrapper is a plain container. So it is when scrollRef names the document in Safari on iOS, and at a page\u2019s first keyboard show in another browser without the VirtualKeyboard API: the browser keeps focus there.',
       },
       {
         name: 'Empty state',
diff --git a/packages/core/src/Chat/useChatKeyboard.test.tsx b/packages/core/src/Chat/useChatKeyboard.test.tsx
index f9462e2c9db4e..1665c496385f9 100644
--- a/packages/core/src/Chat/useChatKeyboard.test.tsx
+++ b/packages/core/src/Chat/useChatKeyboard.test.tsx
@@ -16,18 +16,21 @@ import path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
 import {act, fireEvent, render, screen} from '@testing-library/react';
+import type {ReactNode} from 'react';
 import {ChatComposer} from './ChatComposer';
 import {ChatLayout} from './ChatLayout';
 import {
-  __leavesRevealToBrowserForTest,
-  __learnRevealForTest,
-  __resetRevealForTest,
-  __revealLearnedForTest,
-  editableToClaim,
-} from './useChatKeyboard';
+  ChatComposerInput,
+  type ChatComposerInputHandle,
+} from './ChatComposerInput';
+import {editableToClaim} from './useChatKeyboard';
 import {getKeyboardLayoutGuide} from '../keyboard/keyboardLayoutGuide';
 import {__resetInteractionModalityForTest} from '../utils/interactionModality';
-import {__focusTakeoverCallersForTest} from '../keyboard/keyboardHeight';
+import {
+  __focusTakeoverCallersForTest,
+  __resetDockRevealForTest,
+  getDockReveal,
+} from '../keyboard/keyboardHeight';
 
 // jsdom dates events on the epoch clock, but a browser dates them on
 // performance.now()'s, which the keyboard guide reads them against.
@@ -356,6 +359,8 @@ describe('ChatLayout and the software keyboard', () => {
 
 describe('ChatLayout in a page that scrolls the document', () => {
   beforeEach(() => {
+    // The keyboard module decides a show on a settle timer: tests script it.
+    vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout']});
     // A phone: its primary pointer is a coarse finger.
     vi.stubGlobal('matchMedia', (query: string) => ({
       matches: query === '(pointer: coarse)',
@@ -372,306 +377,351 @@ describe('ChatLayout in a page that scrolls the document', () => {
       configurable: true,
       value: viewport,
     });
-    __resetRevealForTest(window);
+    __resetDockRevealForTest(window);
   });
 
   afterEach(() => {
+    vi.useRealTimers();
     Reflect.deleteProperty(window, 'visualViewport');
     Reflect.deleteProperty(navigator, 'virtualKeyboard');
     vi.unstubAllGlobals();
     vi.restoreAllMocks();
-    __resetRevealForTest(window);
-  });
-
-  // Scripted animation frames: the wait for the browser's pan counts frames,
-  // so these cases run no clock.
-  let frames = new Map<number, FrameRequestCallback>();
-  function scriptFrames() {
-    frames = new Map();
-    let nextFrame = 1;
-    vi.spyOn(window, 'requestAnimationFrame').mockImplementation(callback => {
-      const id = nextFrame;
-      nextFrame += 1;
-      frames.set(id, callback);
-      return id;
+    __resetDockRevealForTest(window);
+  });
+
+  // Time on the keyboard module's settle timer, with no real wait.
+  function wait(ms: number) {
+    act(() => {
+      vi.advanceTimersByTime(ms);
     });
-    vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(id => {
-      frames.delete(id);
+  }
+  // The browser pans the visual viewport, as Safari's reveal of the dock does.
+  function pan(offsetTop: number) {
+    viewport.offsetTop = offsetTop;
+    act(() => {
+      viewport.dispatchEvent(new Event('scroll'));
     });
   }
-  function frame(count = 1) {
+  // A touch event as the browser raises it, at the given points.
+  function touch(type: string, points: {x: number; y: number}[]) {
+    const event = new Event(type, {bubbles: true, cancelable: true});
+    const list = points.map((p, identifier) => ({
+      identifier,
+      clientX: p.x,
+      clientY: p.y,
+    }));
+    Object.assign(event, {
+      touches: type === 'touchend' ? [] : list,
+      changedTouches: list,
+    });
+    return event;
+  }
+  // A reader's drag or fling: a finger down on the page, then up.
+  function drag() {
     act(() => {
-      for (let i = 0; i < count; i += 1) {
-        const queued = [...frames.values()];
-        frames.clear();
-        for (const callback of queued) {
-          callback(performance.now());
-        }
-      }
+      document.dispatchEvent(touch('touchstart', [{x: 5, y: 5}]));
+      document.dispatchEvent(touch('touchend', [{x: 5, y: 50}]));
     });
   }
-  // A finger down on the page, or none.
-  function touches(count: number) {
-    const event = new Event(count > 0 ? 'touchstart' : 'touchend');
-    Object.defineProperty(event, 'touches', {value: {length: count}});
+  function wheel() {
     act(() => {
-      document.dispatchEvent(event);
+      document.dispatchEvent(new Event('wheel'));
     });
   }
-  // The browser pans the visual viewport, as Safari's reveal of the dock does.
-  function pan(offsetTop: number) {
-    viewport.offsetTop = offsetTop;
+  // A tap on the composer's text: whether the composer claimed it.
+  function tapText(field: HTMLElement): boolean {
+    const end = touch('touchend', [{x: 10, y: 10}]);
     act(() => {
-      viewport.dispatchEvent(new Event('scroll'));
+      field.dispatchEvent(touch('touchstart', [{x: 10, y: 10}]));
+      field.dispatchEvent(end);
     });
+    return end.defaultPrevented;
+  }
+  // A first keyboard show the dock stays covered at, then the keyboard goes:
+  // the page has learned that its browser does not pan to the dock.
+  function learnCovered() {
+    report(window.innerHeight - 290);
+    wait(800);
+    report(window.innerHeight);
   }
 
-  function renderDocumentLayout() {
+  function renderDocumentLayout(
+    composer: ReactNode = (
+      <div data-testid="composer">
+        <textarea aria-label="Message" />
+      </div>
+    ),
+  ) {
     return render(
       <ChatLayout
         data-testid="layout"
         scrollRef={{current: document.documentElement}}
-        composer={
-          <div data-testid="composer">
-            <textarea aria-label="Message" />
-          </div>
-        }>
+        composer={composer}>
         <p>Hello</p>
       </ChatLayout>,
     );
   }
 
-  it('lifts the fixed dock nothing in Safari on iOS, whose reveal pans the visual viewport to it and keeps the pan', async () => {
+  it('lifts the fixed dock nothing in Safari on iOS, whose reveal pans the visual viewport to it and keeps the pan', () => {
     const {container} = renderDocumentLayout();
     // Safari's reveal: the keyboard's report comes with a pan by its height.
     viewport.offsetTop = 300;
     report(window.innerHeight - 300);
-    await settle();
+    wait(3000);
     expect(layoutLift(dockOf(container))).toBe(0);
     expect(keyboardRoom(messagesOf())).toBe(0);
+    expect(getDockReveal(window)).toBe(true);
   });
 
-  it('lifts the fixed dock by the keyboard once the visual viewport settles with no pan, as in Firefox for Android', () => {
-    scriptFrames();
+  it('lifts nothing while the browser may still pan, then lifts by the cover 0.7 s after the keyboard\u2019s report, as in Firefox for Android', () => {
     const {container} = renderDocumentLayout();
     report(window.innerHeight - 290);
-    frame(10);
+    wait(650);
     expect(layoutLift(dockOf(container))).toBe(0);
-    frame(40);
+    wait(50);
     expect(layoutLift(dockOf(container))).toBe(290);
     expect(keyboardRoom(messagesOf())).toBe(290);
-    expect(__revealLearnedForTest(window)).toBe(false);
+    expect(getDockReveal(window)).toBe(false);
+  });
+
+  it('keeps the 0.7 s wait through the height reports of the keyboard\u2019s slide, then follows the keyboard\u2019s height', () => {
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 50);
+    wait(100);
+    report(window.innerHeight - 150);
+    wait(100);
+    report(window.innerHeight - 250);
+    wait(450);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    wait(50);
+    expect(layoutLift(dockOf(container))).toBe(250);
+    report(window.innerHeight - 290);
+    expect(layoutLift(dockOf(container))).toBe(290);
+  });
+
+  it('restarts the wait at each pan, so a pan still under way keeps the dock down', () => {
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    wait(500);
+    pan(40);
+    wait(650);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    wait(50);
+    expect(layoutLift(dockOf(container))).toBe(290);
   });
 
-  it('lifts nothing when the visual viewport pans within the wait, as Safari on iOS does', () => {
-    scriptFrames();
+  it('lifts nothing when the visual viewport pans to the dock within the wait, as Safari does', () => {
     const {container} = renderDocumentLayout();
     report(window.innerHeight - 337);
-    frame(20);
+    wait(300);
     pan(337);
-    frame(60);
+    wait(3000);
     expect(layoutLift(dockOf(container))).toBe(0);
-    expect(keyboardRoom(messagesOf())).toBe(0);
-    expect(__revealLearnedForTest(window)).toBe(true);
+    expect(getDockReveal(window)).toBe(true);
     expect(__focusTakeoverCallersForTest(document)).toBe(0);
   });
 
-  it('lifts nothing when the dock is already revealed at the report, and learns nothing from a show that needed no pan', () => {
-    scriptFrames();
+  it('lifts nothing, and learns nothing, when the dock is revealed at the report with no pan', () => {
     viewport.offsetTop = 337;
     const {container} = renderDocumentLayout();
     report(window.innerHeight - 337);
-    frame(60);
+    wait(3000);
     expect(layoutLift(dockOf(container))).toBe(0);
-    expect(__revealLearnedForTest(window)).toBeUndefined();
+    expect(getDockReveal(window)).toBeUndefined();
   });
 
-  it('drops the lift once when the browser pans after the wait, and keeps it off for that show', () => {
-    scriptFrames();
+  it('lifts at the 3 s cap when pans keep restarting the wait, and learns nothing from that show', () => {
     const {container} = renderDocumentLayout();
     report(window.innerHeight - 290);
-    frame(45);
-    expect(layoutLift(dockOf(container))).toBe(290);
-    pan(290);
-    expect(layoutLift(dockOf(container))).toBe(0);
-    pan(0);
-    frame(45);
+    for (let i = 1; i <= 6; i += 1) {
+      wait(500);
+      pan(i % 2 === 1 ? 10 : 0);
+    }
+    expect(layoutLift(dockOf(container))).toBeGreaterThanOrEqual(290);
+    expect(getDockReveal(window)).toBeUndefined();
+    report(window.innerHeight);
     expect(layoutLift(dockOf(container))).toBe(0);
   });
 
   it('after a show that left the dock covered, keeps the composer above the keyboard itself: the takeover, and a lift with no wait', () => {
-    scriptFrames();
     const {container} = renderDocumentLayout();
     expect(__focusTakeoverCallersForTest(document)).toBe(0);
-    report(window.innerHeight - 290);
-    frame(45);
+    learnCovered();
     expect(__focusTakeoverCallersForTest(document)).toBe(1);
-    report(window.innerHeight);
-    expect(layoutLift(dockOf(container))).toBe(0);
     report(window.innerHeight - 290);
     expect(layoutLift(dockOf(container))).toBe(290);
   });
 
-  it('keeps the lift when a finger pans the visual viewport with the keyboard up, as a reader\u2019s scroll in Firefox does', () => {
-    scriptFrames();
-    const {container} = renderDocumentLayout();
-    report(window.innerHeight - 290);
-    frame(45);
-    expect(layoutLift(dockOf(container))).toBe(290);
-    touches(1);
-    pan(156.4);
-    frame(5);
-    pan(290);
-    frame(5);
-    expect(layoutLift(dockOf(container))).toBe(290);
-    expect(__revealLearnedForTest(window)).toBe(false);
-  });
-
-  it('keeps the lift for a small pan with no finger down', () => {
-    scriptFrames();
+  it('after a show the browser panned to, keeps leaving the reveal to it', () => {
     const {container} = renderDocumentLayout();
-    report(window.innerHeight - 290);
-    frame(45);
-    pan(40);
-    frame(5);
-    expect(layoutLift(dockOf(container))).toBe(290);
+    report(window.innerHeight - 337);
+    wait(50);
+    pan(337);
+    report(window.innerHeight);
+    pan(0);
+    report(window.innerHeight - 337);
+    wait(50);
+    pan(337);
+    wait(3000);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    expect(__focusTakeoverCallersForTest(document)).toBe(0);
+    expect(getDockReveal(window)).toBe(true);
   });
 
-  it('drops the lift once for a slow browser whose pan to the dock comes after the settle, and leaves it the reveal', () => {
-    scriptFrames();
+  it('drops the lift once for a slow browser whose pan to the dock comes after the wait, with no input since the show opened', () => {
     const {container} = renderDocumentLayout();
     report(window.innerHeight - 337);
-    frame(45);
+    wait(800);
     expect(layoutLift(dockOf(container))).toBe(337);
     pan(337);
-    frame(2);
     expect(layoutLift(dockOf(container))).toBe(0);
-    expect(__revealLearnedForTest(window)).toBe(true);
+    expect(getDockReveal(window)).toBe(true);
     expect(__focusTakeoverCallersForTest(document)).toBe(0);
   });
 
   it('keeps the lift for a reveal-sized pan after a touch, as a reader\u2019s fling to the end', () => {
-    scriptFrames();
     const {container} = renderDocumentLayout();
     report(window.innerHeight - 290);
-    frame(45);
-    expect(layoutLift(dockOf(container))).toBe(290);
-    touches(1);
-    touches(0);
+    wait(800);
+    drag();
     pan(290);
-    frame(2);
     expect(layoutLift(dockOf(container))).toBe(290);
-    expect(__revealLearnedForTest(window)).toBe(false);
+    expect(getDockReveal(window)).toBe(false);
   });
 
   it('keeps the lift for a reveal-sized pan after a wheel', () => {
-    scriptFrames();
     const {container} = renderDocumentLayout();
     report(window.innerHeight - 290);
-    frame(45);
-    act(() => {
-      document.dispatchEvent(new Event('wheel'));
-    });
+    wait(800);
+    wheel();
     pan(290);
-    frame(2);
     expect(layoutLift(dockOf(container))).toBe(290);
   });
 
-  it('keeps the lift on a show that reached the cap when a touch came before the pan', () => {
-    scriptFrames();
-    let now = 1000;
-    vi.spyOn(performance, 'now').mockImplementation(() => now);
+  it('keeps the input gate closed through a report during a drag, such as a toolbar\u2019s resize', () => {
     const {container} = renderDocumentLayout();
     report(window.innerHeight - 290);
-    // The visual viewport never settles: the cap decides, and nothing is learned.
-    for (let i = 0; i < 31; i += 1) {
-      now += 100;
-      viewport.height = window.innerHeight - 290 - (i % 2);
-      frame();
-    }
+    wait(800);
+    act(() => {
+      document.dispatchEvent(touch('touchstart', [{x: 5, y: 5}]));
+    });
+    report(window.innerHeight - 280);
+    pan(280);
+    expect(layoutLift(dockOf(container))).toBe(280);
+    expect(getDockReveal(window)).toBe(false);
+  });
+
+  it('keeps the lift for a pan smaller than the cover', () => {
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    wait(800);
+    pan(40);
     expect(layoutLift(dockOf(container))).toBe(290);
-    expect(__revealLearnedForTest(window)).toBeUndefined();
-    touches(1);
-    touches(0);
+  });
+
+  it('never flips a page that learned the dock stays covered, at a later show', () => {
+    const {container} = renderDocumentLayout();
+    learnCovered();
+    report(window.innerHeight - 290);
     pan(290);
-    frame(2);
     expect(layoutLift(dockOf(container))).toBe(290);
+    expect(getDockReveal(window)).toBe(false);
   });
 
-  it('never flips a page that learned the dock stays covered at a later show', () => {
-    scriptFrames();
+  it('keeps the lift at a show that reached the cap when a touch came before the pan', () => {
     const {container} = renderDocumentLayout();
     report(window.innerHeight - 290);
-    frame(45);
-    report(window.innerHeight);
+    for (let i = 1; i <= 6; i += 1) {
+      wait(500);
+      pan(i % 2 === 1 ? 10 : 0);
+    }
     report(window.innerHeight - 290);
     expect(layoutLift(dockOf(container))).toBe(290);
+    drag();
     pan(290);
-    frame(2);
     expect(layoutLift(dockOf(container))).toBe(290);
-    expect(__revealLearnedForTest(window)).toBe(false);
   });
 
-  it('restarts the count, but decides nothing, for a pan during the wait that is smaller than the cover', () => {
-    scriptFrames();
-    const {container} = renderDocumentLayout();
-    report(window.innerHeight - 290);
-    frame(10);
-    pan(40);
-    frame(30);
-    expect(layoutLift(dockOf(container))).toBe(0);
-    frame(15);
-    expect(layoutLift(dockOf(container))).toBe(290);
+  it('leaves the composer\u2019s tap to the browser until a show finds the dock covered, then claims it', () => {
+    renderDocumentLayout();
+    const field = screen.getByRole('textbox', {name: 'Message'});
+    expect(tapText(field)).toBe(false);
+    act(() => {
+      field.blur();
+    });
+    learnCovered();
+    expect(tapText(field)).toBe(true);
+  });
+
+  it('keeps the browser\u2019s reveal for the input\u2019s focus() until a show finds the dock covered', () => {
+    let handle: ChatComposerInputHandle | null = null;
+    const {container} = renderDocumentLayout(
+      <ChatComposer
+        onSubmit={() => {}}
+        input={
+          <ChatComposerInput
+            handleRef={h => {
+              handle = h;
+            }}
+          />
+        }
+      />,
+    );
+    const editable = container.querySelector<HTMLElement>(
+      '[contenteditable="true"]',
+    )!;
+    const focus = vi.spyOn(editable, 'focus');
+    act(() => handle!.focus());
+    expect(focus).toHaveBeenLastCalledWith();
+    act(() => {
+      editable.blur();
+    });
+    learnCovered();
+    act(() => handle!.focus());
+    expect(focus).toHaveBeenLastCalledWith({preventScroll: true});
   });
 
-  it('after a show the browser panned to, keeps leaving the reveal to it', () => {
-    scriptFrames();
-    const {container} = renderDocumentLayout();
-    report(window.innerHeight - 337);
-    frame(5);
-    pan(337);
-    frame(2);
-    report(window.innerHeight);
-    pan(0);
-    report(window.innerHeight - 337);
-    frame(3);
-    pan(337);
-    frame(60);
-    expect(layoutLift(dockOf(container))).toBe(0);
-    expect(__focusTakeoverCallersForTest(document)).toBe(0);
-    expect(__revealLearnedForTest(window)).toBe(true);
+  it('leaves the browser\u2019s pan to the dock in place until a show finds the dock covered, then puts a reveal pan back', () => {
+    const scrollIntoView = vi.fn();
+    Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', {
+      configurable: true,
+      value: scrollIntoView,
+    });
+    try {
+      renderDocumentLayout();
+      const field = screen.getByRole('textbox', {name: 'Message'});
+      act(() => {
+        field.focus();
+      });
+      // Safari's reveal: no put-back.
+      report(window.innerHeight - 337);
+      wait(50);
+      pan(337);
+      expect(scrollIntoView).not.toHaveBeenCalled();
+      report(window.innerHeight);
+      pan(0);
+      // A page whose browser leaves the dock covered: a reveal pan goes back.
+      __resetDockRevealForTest(window);
+      learnCovered();
+      report(window.innerHeight - 290);
+      pan(290);
+      expect(scrollIntoView).toHaveBeenCalled();
+    } finally {
+      Reflect.deleteProperty(HTMLElement.prototype, 'scrollIntoView');
+    }
   });
 
   it('learns per window: what one page found never changes another', () => {
-    const root = document.documentElement;
-    const first = {navigator: {}} as unknown as Window;
-    const second = {navigator: {}} as unknown as Window;
-    __learnRevealForTest(first, false);
-    expect(__leavesRevealToBrowserForTest(first, root)).toBe(false);
-    expect(__leavesRevealToBrowserForTest(second, root)).toBe(true);
-    __learnRevealForTest(second, true);
-    expect(__leavesRevealToBrowserForTest(second, root)).toBe(true);
-    expect(__revealLearnedForTest(first)).toBe(false);
-    __resetRevealForTest(first);
-    __resetRevealForTest(second);
-  });
-
-  it('counts frames, not time: a busy device that draws few frames waits longer, up to a cap', () => {
-    scriptFrames();
-    let now = 1000;
-    vi.spyOn(performance, 'now').mockImplementation(() => now);
-    const {container} = renderDocumentLayout();
-    report(window.innerHeight - 290);
-    for (let i = 0; i < 20; i += 1) {
-      now += 100;
-      frame();
-    }
-    expect(layoutLift(dockOf(container))).toBe(0);
-    for (let i = 0; i < 10; i += 1) {
-      now += 100;
-      frame();
+    const frame = document.createElement('iframe');
+    document.body.append(frame);
+    try {
+      renderDocumentLayout();
+      learnCovered();
+      expect(getDockReveal(window)).toBe(false);
+      expect(getDockReveal(frame.contentWindow!)).toBeUndefined();
+    } finally {
+      frame.remove();
     }
-    expect(layoutLift(dockOf(container))).toBe(290);
   });
 
   it('leaves the composer\u2019s focus to Safari there: no focus takeover and no composer group', () => {
@@ -681,7 +731,7 @@ describe('ChatLayout in a page that scrolls the document', () => {
     expect(region.getAttribute('role')).toBeNull();
   });
 
-  it('keeps the lift and the focus takeover for a scrollRef on an inner scroller, in Safari on iOS too', async () => {
+  it('keeps the lift and the focus takeover for a scrollRef on an inner scroller, in Safari on iOS too', () => {
     const scroller = document.createElement('div');
     document.body.append(scroller);
     try {
@@ -699,28 +749,26 @@ describe('ChatLayout in a page that scrolls the document', () => {
       );
       expect(__focusTakeoverCallersForTest(document)).toBe(1);
       report(window.innerHeight - 300);
-      await settle();
       expect(layoutLift(dockOf(container))).toBe(300);
+      expect(getDockReveal(window)).toBeUndefined();
     } finally {
       scroller.remove();
     }
   });
 
-  it('lifts the fixed dock by the keyboard with the VirtualKeyboard API, as in Chrome on Android', async () => {
+  it('lifts the fixed dock by the keyboard with the VirtualKeyboard API, as in Chrome on Android, and never watches the dock there', async () => {
+    vi.useRealTimers();
     Object.defineProperty(navigator, 'virtualKeyboard', {
       configurable: true,
       value: {overlaysContent: false},
     });
     const {container} = renderDocumentLayout();
-    expect(
-      __leavesRevealToBrowserForTest(window, document.documentElement),
-    ).toBe(false);
     report(window.innerHeight - 300);
     await settle();
     expect(layoutLift(dockOf(container))).toBe(300);
     expect(keyboardRoom(messagesOf())).toBe(300);
-    // The reveal wait never runs where the layout guide rides the keyboard.
-    expect(__revealLearnedForTest(window)).toBeUndefined();
+    pan(300);
+    expect(getDockReveal(window)).toBeUndefined();
     expect(__focusTakeoverCallersForTest(document)).toBe(1);
   });
 });
diff --git a/packages/core/src/Chat/useChatKeyboard.ts b/packages/core/src/Chat/useChatKeyboard.ts
index eba85424cc5df..6582bc5f14c4d 100644
--- a/packages/core/src/Chat/useChatKeyboard.ts
+++ b/packages/core/src/Chat/useChatKeyboard.ts
@@ -6,7 +6,7 @@
  * @file useChatKeyboard.ts
  * @input React refs, the keyboard module's height, focus routes and layout
  *   guide, the stream scroll's lock, the motion engine, the touch query and
- *   layout viewport height. Also the input stream's touches and wheels
+ *   layout viewport height
  * @output Exports useChatKeyboard: the lift for ChatLayout's dock and message
  *   area, and the refs for its dock, message area and composer region. It
  *   also tells whether a focus call in the composer skips the browser's reveal
@@ -29,9 +29,13 @@ import {createMotionEngine, type Animator} from '../motion/animator';
 import {
   claimTapFocus,
   findTextEntryControl,
+  getDockReveal,
+  getDockRevealVersion,
   getKeyboardHeight,
+  isDockShowCovered,
   isTextEntryControl,
   refuseFocusReveal,
+  subscribeDockReveal,
   subscribeKeyboardHeight,
 } from '../keyboard/keyboardHeight';
 import {
@@ -46,7 +50,6 @@ import {
 import type {KeyboardTransition} from '../keyboard/keyboardModel';
 import {rideKeyboard} from '../keyboard/rideKeyboard';
 import {layoutViewportHeight} from '../utils/layoutViewport';
-import {subscribeInput} from '../utils/inputStream';
 import {
   useInteractionModalityTrackingFor,
   type InteractionModality,
@@ -210,16 +213,12 @@ export function useChatKeyboard({
     liftStore.get,
   );
   const liftRef = useRef(0);
-  // Whether this keyboard show is the one that found the dock covered, and
-  // whether a touch or a wheel came since its report. Only that show, with no
-  // input yet, can still meet a slow browser's own pan to the dock.
-  const classifyingShowRef = useRef(false);
-  const inputSinceReportRef = useRef(false);
-  // What this window's browser did at a keyboard show, for the effects below.
-  const revealVersion = useSyncExternalStore(
-    subscribeReveal,
-    readRevealVersion,
-    readRevealVersion,
+  // What the window's browser does with the fixed dock, from the keyboard
+  // module: the effects below follow it.
+  const dockRevealVersion = useSyncExternalStore(
+    subscribeDockReveal,
+    getDockRevealVersion,
+    getDockRevealVersion,
   );
   // Set while the guide's ride is under way: the layout waits for it. Each
   // ride's number, so only the latest one hands its translate back.
@@ -246,116 +245,15 @@ export function useChatKeyboard({
     if (root == null || win == null) {
       return undefined;
     }
-    // Where the browser keeps focus and the composer's reveal, each keyboard
-    // show decides once whether the dock rises. A browser that pans the
-    // visual viewport to the fixed dock reveals it: the dock rises nothing,
-    // so a lift never adds to the pan. A dock still covered once the visual
-    // viewport has settled rises by the keyboard's cover, as elsewhere.
-    const unguidedDocument =
-      isDocumentScroller(scrollRef.current) &&
-      keyboardProfileOf(win) !== 'chromium';
-    const leavesReveal = leavesRevealToBrowser(win, scrollRef.current);
-    // The fingers down on the page. A pan under a finger is the reader's, not
-    // the browser's reveal.
-    let touchesDown = 0;
-    const onInput = (event: Event) => {
-      if (event.type !== 'wheel') {
-        touchesDown = (event as TouchEvent).touches?.length ?? 0;
-      }
-      if (event.type === 'touchstart' || event.type === 'wheel') {
-        inputSinceReportRef.current = true;
-      }
-    };
-    const stopInput = unguidedDocument
-      ? (['touchstart', 'touchend', 'touchcancel', 'wheel'] as const).map(
-          type => subscribeInput(win, type, onInput),
-        )
-      : [];
-    // A pan that reveals the fixed dock, with no finger down: with no lift,
-    // the dock would rest at or above the visual viewport's bottom.
-    const isRevealPan = (pan: number | null, inset: number) =>
-      pan != null && inset > 0 && touchesDown === 0 && pan >= inset - 1;
-    let reveal: 'none' | 'watching' | 'revealed' | 'covered' = 'none';
-    let revealFrame = 0;
-    let coveredAt = 0;
-    // The visual viewport's pan with no keyboard up: a show's pan is measured
-    // from it.
-    let restPan = 0;
-    // The visual viewport's pan, or null under a pinch zoom, whose pan is the
-    // reader's.
-    const panOf = () => {
-      const viewport = win.visualViewport;
-      return viewport != null && viewport.scale === 1
-        ? viewport.offsetTop
-        : null;
-    };
-    const stopWatching = () => {
-      if (revealFrame !== 0) {
-        win.cancelAnimationFrame(revealFrame);
-        revealFrame = 0;
-      }
-    };
-    const watchReveal = () => {
-      stopWatching();
-      const startPan = panOf();
-      if (startPan != null && startPan >= getKeyboardHeight(win) - 1) {
-        // Revealed at the report. Only a pan there shows what the browser
-        // does; a show that needed none teaches nothing.
-        reveal = 'revealed';
-        if (startPan > restPan + 0.5) {
-          learnReveal(win, true);
-        }
-        return;
-      }
-      reveal = 'watching';
-      const start = win.performance.now();
-      let height = win.visualViewport?.height;
-      let lastPan = startPan;
-      let stillFrames = 0;
-      const step = () => {
-        revealFrame = 0;
-        const pan = panOf();
-        const inset = getKeyboardHeight(win);
-        if (inset <= 0) {
-          reveal = 'none';
-          return;
-        }
-        // A pan that reveals the dock is the browser's reveal. A smaller one,
-        // or one under a finger, only restarts the count.
-        if (isRevealPan(pan, inset) && pan != null && pan > restPan + 0.5) {
-          reveal = 'revealed';
-          learnReveal(win, true);
-          return;
-        }
-        const nextHeight = win.visualViewport?.height;
-        const isStill = nextHeight === height && pan === lastPan;
-        stillFrames = isStill ? stillFrames + 1 : 0;
-        height = nextHeight;
-        lastPan = pan;
-        const settled = stillFrames >= REVEAL_SETTLE_FRAMES;
-        if (settled || win.performance.now() - start >= REVEAL_WAIT_CAP_MS) {
-          reveal = 'covered';
-          coveredAt = win.visualViewport?.offsetTop ?? 0;
-          commit();
-          // A dock still covered on a still visual viewport: this browser
-          // reveals no fixed dock. From the next render on, the layout keeps
-          // the composer above the keyboard itself, with no wait.
-          if (settled) {
-            classifyingShowRef.current = true;
-            learnReveal(win, false);
-          }
-          return;
-        }
-        revealFrame = win.requestAnimationFrame(step);
-      };
-      revealFrame = win.requestAnimationFrame(step);
-    };
     // A sticky dock rests at the root's bottom edge, which may sit above or
     // below the layout viewport's; a fixed dock rests at the viewport's.
     // While a keyboard is up the dock rises until it clears the keyboard's
-    // cover; without one it rests where the layout puts it.
+    // cover; without one it rests where the layout puts it. Where the browser
+    // keeps the reveal, the dock rises only at a show the keyboard module
+    // finds it covered.
+    const leavesReveal = leavesRevealToBrowser(win, scrollRef.current);
     const liftFor = (inset: number) => {
-      if (inset <= 0 || (leavesReveal && reveal !== 'covered')) {
+      if (inset <= 0 || (leavesReveal && !isDockShowCovered(win))) {
         return 0;
       }
       // In layout px, as the root's rect is, under a pinch zoom too.
@@ -457,67 +355,16 @@ export function useChatKeyboard({
     // so a ride claims the change first.
     let reportedHeight = getKeyboardHeight(win);
     const unsubscribeHeight = subscribeKeyboardHeight(win, event => {
-      if (event.type !== 'viewport') {
-        return;
-      }
-      if (event.height > 0 && reportedHeight <= 0) {
-        inputSinceReportRef.current = false;
-      } else if (event.height <= 0) {
-        classifyingShowRef.current = false;
-      }
-      if (leavesReveal) {
-        const viewport = win.visualViewport;
-        if (event.height <= 0) {
-          stopWatching();
-          reveal = 'none';
-          restPan = panOf() ?? 0;
-        } else if (reveal === 'none') {
-          watchReveal();
-        } else if (
-          reveal === 'covered' &&
-          viewport != null &&
-          viewport.scale === 1 &&
-          viewport.offsetTop > coveredAt + 0.5 &&
-          !inputSinceReportRef.current &&
-          isRevealPan(viewport.offsetTop, event.height)
-        ) {
-          // The browser panned to the dock after the wait: the lift goes, and
-          // it does not come back in this show.
-          reveal = 'revealed';
-          learnReveal(win, true);
-          commit();
-        }
-      } else if (
-        unguidedDocument &&
-        liftRef.current > 0 &&
-        classifyingShowRef.current &&
-        !inputSinceReportRef.current &&
-        isRevealPan(panOf(), event.height)
-      ) {
-        // A slow browser panned to the dock after the show that found it
-        // covered, before any input. The lift goes once, and the browser
-        // keeps the reveal. A pan after a touch or a wheel is the reader's.
-        learnReveal(win, true);
-      }
-      if (event.height !== reportedHeight) {
+      if (event.type === 'viewport' && event.height !== reportedHeight) {
         reportedHeight = event.height;
         commit();
       }
     });
     // Mounted under a keyboard that is already up: take its place at once.
-    if (leavesReveal && reportedHeight > 0) {
-      watchReveal();
-    } else {
-      restPan = panOf() ?? 0;
-    }
     commit();
     return () => {
       unsubscribeHeight();
       unsubscribe?.();
-      stopWatching();
-      for (const stop of stopInput) {
-        stop();
-      }
       ridingRef.current = false;
     };
   }, [
@@ -528,7 +375,7 @@ export function useChatKeyboard({
     dock.animator,
     messages.animator,
     liftStore,
-    revealVersion,
+    dockRevealVersion,
   ]);
 
   // Synchronizes the dock's and the transcript's translates, and the
@@ -592,12 +439,14 @@ export function useChatKeyboard({
       claim: editableToClaim,
       deliver: deliverTap,
     });
-  }, [touchPresentation.isTouch, scrollRef, revealVersion]);
+  }, [touchPresentation.isTouch, scrollRef, dockRevealVersion]);
 
   // A browser that reveals the composer itself pans the visual viewport after
   // the keyboard's report, while the composer still rides up. Chrome 124 on
   // Android pans by the keyboard's whole height. The keyboard module's
-  // reveal-pan watch puts the pan back, so the page does not move.
+  // reveal-pan watch puts the pan back, so the page does not move. In a page
+  // that scrolls the document with no layout guide, the watch also learns
+  // whether the browser reveals the fixed dock. If it does, it keeps that pan.
   // Synchronizes the keyboard module's reports, under a finger only.
   useIsomorphicLayoutEffect(() => {
     const composer = composerRef.current;
@@ -605,12 +454,13 @@ export function useChatKeyboard({
     if (
       !touchPresentation.isTouch ||
       composer == null ||
-      !followsKeyboard(win) ||
-      leavesRevealToBrowser(win, scrollRef.current)
+      !followsKeyboard(win)
     ) {
       return undefined;
     }
-    const pans = watchPans(win, focused => composer.contains(focused));
+    const pans = watchPans(win, focused => composer.contains(focused), {
+      dock: isUnguidedDocument(win, scrollRef.current),
+    });
     const unsubscribe = subscribeKeyboardHeight(win, event => {
       if (event.type === 'viewport') {
         pans.report(event.height);
@@ -620,7 +470,7 @@ export function useChatKeyboard({
       unsubscribe();
       pans.stop();
     };
-  }, [touchPresentation.isTouch, scrollRef, revealVersion]);
+  }, [touchPresentation.isTouch, scrollRef]);
 
   // Synchronizes the keyboard module's focus takeover, and the region's group
   // role, with the touch presentation. Every other move into the composer's
@@ -656,7 +506,7 @@ export function useChatKeyboard({
       stopTakeover();
       composer.removeAttribute('role');
     };
-  }, [touchPresentation.isTouch, readModality, scrollRef, revealVersion]);
+  }, [touchPresentation.isTouch, readModality, scrollRef, dockRevealVersion]);
 
   // A focus call skips the browser's reveal only where ChatLayout keeps the
   // composer above the keyboard itself. The server has no keyboard profile.
@@ -666,7 +516,7 @@ export function useChatKeyboard({
     return win == null || !leavesRevealToBrowser(win, scroller);
   }, [scrollRef]);
   const isKeyboardSurface = useSyncExternalStore(
-    subscribeReveal,
+    subscribeDockReveal,
     readKeyboardSurface,
     readKeyboardSurfaceOnServer,
   );
@@ -680,59 +530,13 @@ export function useChatKeyboard({
   };
 }
 
-// How long a keyboard show waits for the browser's own pan to the dock. The
-// visual viewport must stay still for these frames, with a cap in wall time.
-// A busy device draws fewer frames, so it waits longer. Safari on iOS pans up
-// to about 400 ms after the keyboard's report.
-const REVEAL_SETTLE_FRAMES = 40;
-const REVEAL_WAIT_CAP_MS = 3000;
-
 const readKeyboardSurfaceOnServer = () => true;
 
-// What each window's browser did with a fixed dock at a keyboard show. True:
-// it panned the visual viewport to reveal the dock. False: the dock stayed
-// covered. Unknown until the first show.
-const revealLearned = new WeakMap<Window, boolean>();
-const revealListeners = new Set<() => void>();
-let revealVersionNow = 0;
-function learnReveal(win: Window, pans: boolean): void {
-  if (revealLearned.get(win) === pans) {
-    return;
-  }
-  revealLearned.set(win, pans);
-  revealVersionNow += 1;
-  for (const listener of revealListeners) {
-    listener();
-  }
-}
-function subscribeReveal(listener: () => void): () => void {
-  revealListeners.add(listener);
-  return () => {
-    revealListeners.delete(listener);
-  };
+// A page that scrolls the document, in a browser with no layout guide: there
+// the browser may reveal the fixed dock itself.
+function isUnguidedDocument(win: Window, scroller: Element | null): boolean {
+  return isDocumentScroller(scroller) && keyboardProfileOf(win) !== 'chromium';
 }
-const readRevealVersion = () => revealVersionNow;
-
-/** What `win`'s browser was found to do with a fixed dock (tests only). */
-export function __revealLearnedForTest(win: Window): boolean | undefined {
-  return revealLearned.get(win);
-}
-
-/** Forgets what `win`'s browser was found to do (tests only). */
-export function __resetRevealForTest(win: Window): void {
-  if (revealLearned.delete(win)) {
-    revealVersionNow += 1;
-    for (const listener of revealListeners) {
-      listener();
-    }
-  }
-}
-
-/** Records what `win`'s browser did with a fixed dock (tests only). */
-export const __learnRevealForTest = learnReveal;
-
-/** Whether ChatLayout leaves the composer's reveal to `win` (tests only). */
-export const __leavesRevealToBrowserForTest = leavesRevealToBrowser;
 
 /**
  * Whether the browser keeps focus and the composer's reveal. That is a page
@@ -743,11 +547,7 @@ export const __leavesRevealToBrowserForTest = leavesRevealToBrowser;
  * above the keyboard itself.
  */
 function leavesRevealToBrowser(win: Window, scroller: Element | null): boolean {
-  return (
-    isDocumentScroller(scroller) &&
-    keyboardProfileOf(win) !== 'chromium' &&
-    revealLearned.get(win) !== false
-  );
+  return isUnguidedDocument(win, scroller) && getDockReveal(win) !== false;
 }
 
 // The document's root and body both scroll the page.
diff --git a/packages/core/src/keyboard/README.md b/packages/core/src/keyboard/README.md
index ee3b113789ad0..7ac3fa02b2f00 100644
--- a/packages/core/src/keyboard/README.md
+++ b/packages/core/src/keyboard/README.md
@@ -71,7 +71,15 @@ that times motion with it. Everything here is internal to
   under a coarse primary pointer; under a fine one it registers no touch
   listener. `watchPans(win, owns)` (`keyboardTarget.ts`) runs that loop on
   each height the module reports: the keyboard targets and ChatLayout's
-  composer watch with it.
+  composer watch with it. With `dock` (off by default), the watch also
+  decides once per keyboard show whether the browser pans the visual viewport
+  to a fixed dock in a page that scrolls the document. A pan marks a browser
+  that reveals the dock: no pan is put back. A dock still covered 0.7 s after
+  the show's opening report marks one that does not. Only a pan restarts that
+  wait, up to 3 s; the height reports of the keyboard's slide do not.
+  `getDockReveal(win)` keeps that per window, and `getKeyboardPan(win)` gives
+  the pan read with each report. Only a touch or a wheel since the show's
+  opening report closes the late-pan check; no later report reopens it.
 - **Keyboard targets (`keyboardTarget.ts`):** a target keeps the focused field
   inside it above the keyboard, and registers so a field inside moves nothing
   itself (`registerKeyboardTarget`, `isInsideKeyboardTarget`).
diff --git a/packages/core/src/keyboard/keyboardHeight.test.ts b/packages/core/src/keyboard/keyboardHeight.test.ts
index 45a69be6ec9b2..551d37ecb89ba 100644
--- a/packages/core/src/keyboard/keyboardHeight.test.ts
+++ b/packages/core/src/keyboard/keyboardHeight.test.ts
@@ -28,6 +28,7 @@ import {
   findTextEntryControl,
   focusAtPoint,
   getKeyboardHeight,
+  getKeyboardPan,
   isKeyboardMeasurable,
   isTextEntryControl,
   measureKeyboardHeight,
@@ -916,6 +917,71 @@ describe('the browser\u2019s own reveal pan (FR4)', () => {
     second.stop();
     expect(remove.mock.calls.map(([type]) => type)).toEqual(['touchstart']);
   });
+
+  it('with the dock option off, reports and listens exactly as without it', () => {
+    const runs: boolean[][] = [];
+    for (const options of [{}, {dock: false}]) {
+      const add = vi.spyOn(window, 'addEventListener');
+      const region = document.createElement('div');
+      const field = document.createElement('textarea');
+      region.append(field);
+      document.body.append(region);
+      const watch = watchRevealPan(window, {
+        owns: focused => region.contains(focused),
+        ...options,
+      });
+      field.focus();
+      viewport.offsetTop = 0;
+      viewport.height = window.innerHeight - 300;
+      watch.report();
+      const seen = [watch.isRevealPan(300), watch.dockReport(300)];
+      viewport.offsetTop = 300;
+      seen.push(watch.isRevealPan(300), watch.dockReport(300));
+      document.dispatchEvent(new Event('touchstart'));
+      seen.push(watch.isRevealPan(300));
+      runs.push(seen);
+      expect(add.mock.calls.map(([type]) => type)).toEqual(['touchstart']);
+      watch.stop();
+      add.mockRestore();
+      document.body.replaceChildren();
+    }
+    expect(runs[1]).toEqual(runs[0]);
+    expect(runs[0]).toEqual([false, false, true, false, false]);
+  });
+
+  it('with the dock option, shares one wheel subscription among its watches', () => {
+    const add = vi.spyOn(window, 'addEventListener');
+    const remove = vi.spyOn(window, 'removeEventListener');
+    const first = watchRevealPan(window, {owns: () => true, dock: true});
+    const second = watchRevealPan(window, {owns: () => true, dock: true});
+    expect(add.mock.calls.map(([type]) => type).sort()).toEqual([
+      'touchstart',
+      'wheel',
+    ]);
+    first.stop();
+    expect(remove).not.toHaveBeenCalled();
+    second.stop();
+    expect(remove.mock.calls.map(([type]) => type).sort()).toEqual([
+      'touchstart',
+      'wheel',
+    ]);
+  });
+});
+
+describe('the visual viewport\u2019s pan with each report', () => {
+  it('is read with the report\u2019s height, and is none under a pinch zoom', () => {
+    const stop = subscribeKeyboardHeight(window, () => {});
+    viewport.offsetTop = 120;
+    viewport.dispatchEvent(new Event('scroll'));
+    expect(getKeyboardPan(window)).toBe(120);
+    // No report yet: the reader sees the last report's pan.
+    viewport.offsetTop = 200;
+    expect(getKeyboardPan(window)).toBe(120);
+    viewport.scale = 2;
+    viewport.dispatchEvent(new Event('scroll'));
+    expect(getKeyboardPan(window)).toBeNull();
+    stop();
+  });
 });
 
 describe('the text-entry predicate', () => {
diff --git a/packages/core/src/keyboard/keyboardHeight.ts b/packages/core/src/keyboard/keyboardHeight.ts
index d3add41236e85..993f0bf83619d 100644
--- a/packages/core/src/keyboard/keyboardHeight.ts
+++ b/packages/core/src/keyboard/keyboardHeight.ts
@@ -8,8 +8,9 @@
  *   resize, scroll and touch), and the layout viewport's height
  * @output The on-screen keyboard module: measureKeyboardHeight,
  *   isKeyboardMeasurable, hasVirtualKeyboard, subscribeKeyboardHeight,
- *   getKeyboardHeight, isTextEntryControl, findTextEntryControl,
- *   refuseFocusReveal and watchRevealPan
+ *   getKeyboardHeight, getKeyboardPan, isTextEntryControl,
+ *   findTextEntryControl, refuseFocusReveal and watchRevealPan. It also keeps
+ *   what a window's browser does with a fixed dock (getDockReveal)
  * @position Core's one source for the on-screen keyboard. It is internal to
  *   core and never exported from the package.
  *
@@ -100,6 +101,8 @@ export type KeyboardHeightEvent =
 
 interface KeyboardStore {
   height: number;
+  /** The visual viewport's pan at the last report (getKeyboardPan). */
+  pan: number | null;
   listeners: Set<(event: KeyboardHeightEvent) => void>;
   /** The subscribers that asked for focus moves too (the layout guide). */
   focusListeners: Set<(event: KeyboardHeightEvent) => void>;
@@ -114,6 +117,7 @@ function storeOf(win: Window): KeyboardStore {
   if (store == null) {
     store = {
       height: 0,
+      pan: null,
       listeners: new Set(),
       focusListeners: new Set(),
       detach: null,
@@ -147,6 +151,7 @@ function isHideStep(win: Window, shown: number, height: number): boolean {
 function attach(win: Window, store: KeyboardStore): () => void {
   const viewport = win.visualViewport;
   store.height = measureKeyboardHeight(win);
+  store.pan = measurePan(win);
   // Set while a step of a hide waits. The store keeps the height it reported,
   // so every reader lays out once, when the keyboard comes to rest.
   let stepTimer: ReturnType<typeof setTimeout> | null = null;
@@ -154,6 +159,7 @@ function attach(win: Window, store: KeyboardStore): () => void {
   let stepLimit = 0;
   const deliver = (height: number, timeStamp: number) => {
     store.height = height;
+    store.pan = measurePan(win);
     const report: KeyboardHeightEvent = {type: 'viewport', height, timeStamp};
     for (const listener of [...store.listeners]) {
       listener(report);
@@ -295,6 +301,23 @@ export function getKeyboardHeight(win: Window): number {
   return store?.detach != null ? store.height : measureKeyboardHeight(win);
 }
 
+// The visual viewport's pan down the layout viewport, CSS px, or null under a
+// pinch zoom, whose pan is the reader's.
+function measurePan(win: Window): number | null {
+  const viewport = win.visualViewport;
+  return viewport != null && viewport.scale === 1 ? viewport.offsetTop : null;
+}
+
+/**
+ * How far `win`'s visual viewport is panned down the layout viewport, CSS px,
+ * or null under a pinch zoom. While the module listens, it is the pan read
+ * with the last report's height, so a reader adds no read of its own.
+ */
+export function getKeyboardPan(win: Window): number | null {
+  const store = stores.get(win);
+  return store?.detach != null ? store.pan : measurePan(win);
+}
+
 /**
  * Whether focusing `element` brings up a keyboard for typing text. A control
  * with `inputmode="none"` brings up none.
@@ -464,6 +487,13 @@ export interface WatchRevealPanOptions {
   owns: (focused: HTMLElement) => boolean;
   /** Called on every touch start, which ends the watch for the report. */
   onTouch?: () => void;
+  /**
+   * The field sits in a fixed dock of a page that scrolls the document. Each
+   * keyboard show then decides once whether the browser pans the visual
+   * viewport to the dock (getDockReveal). Off by default.
+   * @default false
+   */
+  dock?: boolean;
 }
 
 /** A watch for the browser's own reveal pan (see watchRevealPan). */
@@ -478,6 +508,12 @@ export interface RevealPanWatch {
    * the layout viewport's top, or else a probe fixed where the viewport sat.
    */
   putBack: (anchor?: Element | null) => void;
+  /**
+   * With `dock`, feeds a keyboard report to the dock's watch. True while the
+   * browser keeps the reveal, so the caller puts no pan back. Without `dock`,
+   * always false.
+   */
+  dockReport: (height: number) => boolean;
   /** Ends the watch; the shared touch subscription goes with the last watch. */
   stop: () => void;
 }
@@ -519,6 +555,246 @@ function watchTouchStarts(doc: Document, onTouchStart: () => void): () => void {
   };
 }
 
+// One shared wheel subscription per document serves every dock watch in it,
+// as the touch subscription above serves the reveal-pan watches.
+const wheelWatches = new WeakMap<
+  Document,
+  {stop: () => void; watches: Set<() => void>}
+>();
+
+function watchWheels(doc: Document, onWheel: () => void): () => void {
+  let shared = wheelWatches.get(doc);
+  if (shared == null) {
+    const view = doc.defaultView;
+    if (view == null) {
+      return () => {};
+    }
+    const watches = new Set<() => void>();
+    const stop = subscribeInput(view, 'wheel', () => {
+      for (const watch of [...watches]) {
+        watch();
+      }
+    });
+    shared = {stop, watches};
+    wheelWatches.set(doc, shared);
+  }
+  shared.watches.add(onWheel);
+  return () => {
+    const current = wheelWatches.get(doc);
+    if (current == null || !current.watches.delete(onWheel)) {
+      return;
+    }
+    if (current.watches.size === 0) {
+      current.stop();
+      wheelWatches.delete(doc);
+    }
+  };
+}
+
+// How long a dock's keyboard show waits for the browser's own pan to the
+// dock, from the show's opening report. Only a pan restarts the wait: the
+// height reports of the keyboard's slide do not. The cap ends a wait that pans
+// keep restarting. Safari on iOS pans up to about 400 ms after the keyboard's
+// report.
+const DOCK_REVEAL_SETTLE_MS = 700;
+const DOCK_REVEAL_CAP_MS = 3000;
+
+// What each window's browser did with a fixed dock at a keyboard show. True:
+// it panned the visual viewport to the dock. False: the dock stayed covered.
+const dockReveals = new WeakMap<Window, boolean>();
+// The windows whose current show found the dock covered at the wait's cap.
+// Such a show lifts the dock but teaches nothing.
+const coveredShows = new WeakSet<Window>();
+const dockRevealListeners = new Set<() => void>();
+let dockRevealVersion = 0;
+
+function notifyDockReveal(): void {
+  dockRevealVersion += 1;
+  for (const listener of [...dockRevealListeners]) {
+    listener();
+  }
+}
+
+function learnDockReveal(win: Window, pans: boolean): void {
+  if (dockReveals.get(win) !== pans) {
+    dockReveals.set(win, pans);
+    notifyDockReveal();
+  }
+}
+
+/**
+ * What `win`'s browser was found to do with a fixed dock at a keyboard show.
+ * True: it pans the visual viewport to the dock. False: it leaves the dock
+ * covered. Undefined until a reveal-pan watch with `dock` decides it.
+ */
+export function getDockReveal(win: Window): boolean | undefined {
+  return dockReveals.get(win);
+}
+
+/** Whether the fixed dock in `win` stays covered at this keyboard show. */
+export function isDockShowCovered(win: Window): boolean {
+  return dockReveals.get(win) === false || coveredShows.has(win);
+}
+
+/** Calls `listener` when getDockReveal or isDockShowCovered changes. */
+export function subscribeDockReveal(listener: () => void): () => void {
+  dockRevealListeners.add(listener);
+  return () => {
+    dockRevealListeners.delete(listener);
+  };
+}
+
+/** A number that changes whenever a window's dock reveal changes. */
+export function getDockRevealVersion(): number {
+  return dockRevealVersion;
+}
+
+/**
+ * Test-only: forgets what `win`'s browser was found to do with a fixed dock.
+ * Not part of the runtime API.
+ *
+ * @internal
+ */
+export function __resetDockRevealForTest(win: Window): void {
+  const known = dockReveals.delete(win);
+  if (coveredShows.delete(win) || known) {
+    notifyDockReveal();
+  }
+}
+
+// The dock's watch: one decision per keyboard show. A pan to the dock marks
+// a browser that reveals it. A dock still covered when the wait ends marks
+// one that does not, and the dock rises. Only the show that
+// learned that, with no touch or wheel since its opening report, still meets
+// a slow browser's pan: the lift then goes.
+function watchDock(win: Window): {
+  report: (height: number) => boolean;
+  input: () => void;
+  stop: () => void;
+} {
+  let show: 'none' | 'watching' | 'revealed' | 'covered' = 'none';
+  let restPan = getKeyboardPan(win) ?? 0;
+  let lastPan = getKeyboardPan(win);
+  let coveredPan = 0;
+  let isClassifying = false;
+  // Only the next show's opening report clears it.
+  let inputSinceShow = false;
+  let settleTimer: ReturnType<typeof setTimeout> | null = null;
+  let capTimer: ReturnType<typeof setTimeout> | null = null;
+  const clearTimers = () => {
+    if (settleTimer != null) {
+      clearTimeout(settleTimer);
+      settleTimer = null;
+    }
+    if (capTimer != null) {
+      clearTimeout(capTimer);
+      capTimer = null;
+    }
+  };
+  // A pan that reveals the dock before any input: with no lift, the dock
+  // would rest at or above the visual viewport's bottom.
+  const isRevealPan = (pan: number | null, height: number): pan is number =>
+    pan != null && !inputSinceShow && pan >= height - 1;
+  const cover = (learn: boolean) => {
+    clearTimers();
+    show = 'covered';
+    coveredPan = getKeyboardPan(win) ?? 0;
+    if (learn) {
+      isClassifying = true;
+      learnDockReveal(win, false);
+    } else {
+      coveredShows.add(win);
+      notifyDockReveal();
+    }
+  };
+  const restartSettle = () => {
+    if (settleTimer != null) {
+      clearTimeout(settleTimer);
+    }
+    settleTimer = setTimeout(() => {
+      settleTimer = null;
+      if (show === 'watching') {
+        cover(true);
+      }
+    }, DOCK_REVEAL_SETTLE_MS);
+  };
+  const markInput = () => {
+    inputSinceShow = true;
+  };
+  const stopWheels = watchWheels(win.document, markInput);
+  const report = (height: number): boolean => {
+    const pan = getKeyboardPan(win);
+    const panned =
+      pan == null || lastPan == null
+        ? pan !== lastPan
+        : Math.abs(pan - lastPan) > 0.5;
+    lastPan = pan;
+    if (height <= 0) {
+      clearTimers();
+      show = 'none';
+      isClassifying = false;
+      restPan = pan ?? 0;
+      if (coveredShows.delete(win)) {
+        notifyDockReveal();
+      }
+      return dockReveals.get(win) !== false;
+    }
+    if (show === 'none') {
+      inputSinceShow = false;
+      if (dockReveals.get(win) === false) {
+        show = 'covered';
+        return false;
+      }
+      if (pan != null && pan >= height - 1) {
+        // Revealed at the report. Only a pan there shows what the browser
+        // does; a show that needed none teaches nothing.
+        show = 'revealed';
+        if (pan > restPan + 0.5) {
+          learnDockReveal(win, true);
+        }
+        return true;
+      }
+      show = 'watching';
+      capTimer = setTimeout(() => {
+        capTimer = null;
+        if (show === 'watching') {
+          cover(false);
+        }
+      }, DOCK_REVEAL_CAP_MS);
+      restartSettle();
+      return true;
+    }
+    if (show === 'watching') {
+      if (isRevealPan(pan, height) && pan > restPan + 0.5) {
+        clearTimers();
+        show = 'revealed';
+        learnDockReveal(win, true);
+      } else if (panned) {
+        restartSettle();
+      }
+      return true;
+    }
+    if (show === 'covered' && (isClassifying || coveredShows.has(win))) {
+      if (isRevealPan(pan, height) && pan > coveredPan + 0.5) {
+        show = 'revealed';
+        isClassifying = false;
+        coveredShows.delete(win);
+        learnDockReveal(win, true);
+      }
+      return true;
+    }
+    return show === 'revealed';
+  };
+  return {
+    report,
+    input: markInput,
+    stop: () => {
+      clearTimers();
+      stopWheels();
+    },
+  };
+}
+
 /**
  * Some browsers reveal a focused field themselves, after the keyboard's
  * report, by panning the visual viewport to it while the keyboard still
@@ -540,14 +816,16 @@ function watchTouchStarts(doc: Document, onTouchStart: () => void): () => void {
  */
 export function watchRevealPan(
   win: Window,
-  {owns, onTouch}: WatchRevealPanOptions,
+  {owns, onTouch, dock = false}: WatchRevealPanOptions,
 ): RevealPanWatch {
   const doc = win.document;
+  const dockWatch = dock ? watchDock(win) : null;
   let atReport: {x: number; y: number; top: number; scale: number} | null =
     null;
   let touchedSinceReport = false;
   const stopTouchStarts = watchTouchStarts(doc, () => {
     touchedSinceReport = true;
+    dockWatch?.input();
     onTouch?.();
   });
   return {
@@ -605,7 +883,14 @@ export function watchRevealPan(
       probe.scrollIntoView(options);
       probe.remove();
     },
-    stop: stopTouchStarts,
+    dockReport: height => dockWatch?.report(height) ?? false,
+    stop:
+      dockWatch == null
+        ? stopTouchStarts
+        : () => {
+            stopTouchStarts();
+            dockWatch.stop();
+          },
   };
 }
 
diff --git a/packages/core/src/keyboard/keyboardTarget.ts b/packages/core/src/keyboard/keyboardTarget.ts
index 4b5d41d1cff2b..1192d30da5f25 100644
--- a/packages/core/src/keyboard/keyboardTarget.ts
+++ b/packages/core/src/keyboard/keyboardTarget.ts
@@ -430,6 +430,17 @@ export function deliverTap(
   control.dispatchEvent(click);
 }
 
+/** The caller's rules for watchPans. */
+export interface WatchPansOptions {
+  /**
+   * The field sits in a fixed dock of a page that scrolls the document
+   * (watchRevealPan's `dock`). While the browser keeps the dock's reveal, no
+   * pan is put back. Off by default.
+   * @default false
+   */
+  dock?: boolean;
+}
+
 /**
  * Puts back a pan the browser makes on its own after a keyboard report. This
  * happens, for example, after a focus no claim saw: a script's `focus()` while
@@ -440,11 +451,16 @@ export function deliverTap(
 export function watchPans(
   win: Window,
   owns: (focused: Element) => boolean,
+  {dock = false}: WatchPansOptions = {},
 ): {report(height: number): void; stop(): void} {
-  const watch = watchRevealPan(win, {owns});
+  const watch = watchRevealPan(win, {owns, dock});
   let lastHeight = getKeyboardHeight(win);
   return {
     report(height: number): void {
+      if (watch.dockReport(height)) {
+        lastHeight = height;
+        return;
+      }
       if (height !== lastHeight) {
         lastHeight = height;
         watch.report();

From e18165abfbf96561f4d8be1ceebaac7207bea09c Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 8 Nov 2026 12:45:24 -0800
Subject: [PATCH 08/16] fix(ChatLayout): a pan to the dock decides only its own
 show

Firefox for Android pans to the composer at some shows and not at
others, so a pan proves nothing about the browser. A reveal pan now
decides its own show alone, and only "covers" is learned: from a
show still covered when the wait ends, with no touch or wheel in
the wait. A show with input in the wait learns nothing; where the
dock rests when the wait ends decides it. A late pan after the
lift, before any input, drops the lift and forgets "covers".
---
 docs/specs/AST-099-mobile-keyboard/spec.md    |  42 +++---
 .../cli/assets/docs/browser-support.doc.mjs   |   2 +-
 packages/core/src/Chat/ChatLayout.doc.mjs     |   8 +-
 .../core/src/Chat/useChatKeyboard.test.tsx    | 127 +++++++++++++++---
 packages/core/src/Chat/useChatKeyboard.ts     |   8 +-
 packages/core/src/keyboard/README.md          |  16 ++-
 packages/core/src/keyboard/keyboardHeight.ts  |  97 +++++++------
 7 files changed, 206 insertions(+), 94 deletions(-)

diff --git a/docs/specs/AST-099-mobile-keyboard/spec.md b/docs/specs/AST-099-mobile-keyboard/spec.md
index 02e9738707c88..bbc6ddf391df0 100644
--- a/docs/specs/AST-099-mobile-keyboard/spec.md
+++ b/docs/specs/AST-099-mobile-keyboard/spec.md
@@ -105,12 +105,12 @@ app to turn on.
   browser and as a home-screen app, pans the visual viewport to the fixed dock
   and keeps the pan. There ChatLayout leaves focus and the reveal to the
   browser, and the dock rises nothing: the composer is not a keyboard-aware
-  surface (FR4). ChatLayout learns this from the browser's behavior. Without the
-  VirtualKeyboard API, a page's first keyboard show leaves focus to the browser
-  and watches the visual viewport. A pan to the dock marks a browser that
-  reveals it. A dock still covered once the visual viewport settles, within a
-  bounded wait (Gap 16), rises by the keyboard's cover. From then on, the
-  composer is a keyboard-aware surface there, as elsewhere. FR9's
+  surface (FR4). ChatLayout reads this from the browser's behavior at each show.
+  Without the VirtualKeyboard API, each keyboard show leaves focus to the
+  browser and watches the visual viewport, until a show finds the dock covered.
+  A show where the browser pans to the dock needs no lift. A dock still covered
+  when a bounded wait ends (Gap 16) rises by the keyboard's cover. From then on,
+  the composer is a keyboard-aware surface there, as elsewhere. FR9's
   docked ride is the one exception: Core moves an app's docked bar as FR9 sets
   out. How the value reaches styles is `architecture:react-component-runtime`
   INV11. Riding the keyboard's motion layers on top of that layout, so layout
@@ -138,8 +138,8 @@ app to turn on.
   way. A document scroll that still happens while the page is scroll-locked,
   such as on returning to the app, is put back in the same frame. FR3 names two
   exceptions when ChatLayout's `scrollRef` names the document's scroller: its
-  composer in Safari on iOS, and a page's first keyboard show in another browser
-  without the VirtualKeyboard API (Gap 16).
+  composer in Safari on iOS, and in another browser without the VirtualKeyboard
+  API, each keyboard show until one finds the dock covered (Gap 16).
 - **FR5 — Moving a surface dismisses the keyboard.** When a surface that holds
   the focused control starts to move, such as a sheet dragged between heights,
   a drag to dismiss, or a close, the control is blurred so the keyboard
@@ -391,15 +391,19 @@ No covered field meets FR9 on `main`. Each gap below is open.
   Safari on iOS (`packages/core/src/keyboard/useMobileKeyboard.ts`). But
   Firefox reports the keyboard's hide once, at its end. The sheet's content
   moves at that report, in one frame, instead of riding from the blur (FR3).
-- **Gap 16 — The first keyboard show of a document-scrolling ChatLayout without
-  the VirtualKeyboard API.** ChatLayout cannot tell before that show whether the
-  browser pans to its fixed dock (FR3). So the first show leaves focus to the
-  browser. In Firefox for Android, the first keyboard show on each page leaves
-  the composer covered for about 0.7 s after the keyboard's report. Only a pan
-  of the visual viewport restarts that wait, and the wait ends at 3 s at most.
-  Every later show lifts the dock at once. On the iOS Simulator, Safari's pan
-  arrived 0 to 384 ms after the keyboard's report. A short cover once, at
-  Firefox's first show, is better than a lift and then a drop in a slow Safari.
+- **Gap 16 — The first covered keyboard show of a document-scrolling ChatLayout
+  without the VirtualKeyboard API.** ChatLayout cannot tell before a show
+  whether the browser pans to its fixed dock (FR3). So each show leaves focus to
+  the browser until one show finds the dock covered. A show where the browser
+  pans to the dock needs no lift, and teaches nothing: Firefox for Android pans
+  at some shows and not at others. In Firefox for Android, the first show it
+  leaves covered keeps the composer covered for up to about 0.7 s after the
+  keyboard's report. Only a pan of the visual viewport restarts that wait, and
+  the wait ends at 3 s at most. Every later show lifts the dock at once. A show
+  with a touch or a wheel in the wait also lifts only when the wait ends, and
+  teaches nothing. On the iOS Simulator, Safari's pan arrived 0 to 384 ms after
+  the keyboard's report. A short cover once, at Firefox's first covered show, is
+  better than a lift and then a drop in a slow Safari.
 
 ### Follow-up
 
@@ -423,8 +427,8 @@ that sets its own `translate`, to the app.
 | FR2–FR5  | Safari on iOS in the iOS Simulator or on a device, top-level document                                        | focus routes, keyboard shown and hidden, page panned and pinch-zoomed, a sheet moved, ChatLayout's composer, in Safari and as a home-screen app                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | The page lurches, the field ends under the keyboard, or the height is wrong after a pan or zoom                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | FR2–FR5  | Release gate: a physical iPhone in a top-level document (DEC-3)                                              | iPhone Safari with the toolbar expanded and collapsed; iPhone home-screen app; the phone's refresh rate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | The page lurches, the field ends under the keyboard, or the surface does not follow the keyboard                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | FR3–FR4  | ChatLayout's keyboard tests in jsdom and its interaction proofs in Chromium and WebKit                       | the fixed and the sticky dock with the keyboard shown and hidden; the message area's end padding; a transcript at its newest message; a page pinch-zoomed with the keyboard up; focus by tap, Tab, `focus()` and Done, under a finger and under a mouse                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | The dock left under the keyboard or lifted with none; the newest message unable to scroll above the composer; a transcript at its newest message left behind; the page panned to the composer's text under a finger, outside FR3's document-scroll exception; focus left in the text after Done, or the composer group focusable outside Done's park                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| FR3–FR4  | Firefox for Android in the emulator, top-level document                                                      | ChatLayout whose `scrollRef` names the document, the page's first keyboard show: a tap on the composer, the keyboard shown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Once the visual viewport settles, the composer does not rest on the keyboard: its bottom sits more than 0.5 CSS px below the visual viewport's bottom                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| FR3–FR4  | Firefox for Android in the emulator, top-level document                                                      | The same page's second keyboard show: a tap on the composer, the keyboard shown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | The composer does not rest on the keyboard at once: its bottom sits more than 0.5 CSS px below the visual viewport's bottom                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| FR3–FR4  | Firefox for Android in the emulator, top-level document                                                      | ChatLayout whose `scrollRef` names the document, the page's first keyboard show: a tap on the composer, the keyboard shown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Once the wait ends (Gap 16), the composer does not rest on the keyboard: its bottom sits more than 0.5 CSS px below the visual viewport's bottom                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| FR3–FR4  | Firefox for Android in the emulator, top-level document                                                      | The same page's next keyboard show after one that left the composer covered: a tap on the composer, the keyboard shown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | The composer does not rest on the keyboard at once: its bottom sits more than 0.5 CSS px below the visual viewport's bottom                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | FR8      | ChatLayout's interaction proofs in Chromium with Chrome's keyboard report                                    | the dock riding Gboard's slide up from the report and down from the blur; reduced motion on                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | The dock lagging Gboard's slide, laying out or painting per frame, or jumping at the hand-back; the dock travelling under reduced motion instead of DR2's cross-fade                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | FR9      | ChatLayout's keyboard tests in jsdom                                                                         | ChatComposer in the fixed and the sticky dock, above the keyboard after each focus route                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | ChatComposer ending under the keyboard, or moved a second time inside its dock, after any focus route                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | FR9      | TBD (Gap 1–11): a focus test per covered field, driving one keyboard change                                  | each covered field in the page, a Tall and a `hug` BottomSheet, ChatLayout's fixed and sticky dock, an app's fixed bar docked to the bottom edge with no `translate` of its own, and a fixed Toolbar docked there; focus by tap, Tab, and `focus()`; a field in scrolling content in the page and in a nested scroller; a field near its scroller's end; a field in a scroller inside a full-viewport fixed container                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | A focused page field or Core-host field left under the keyboard or less than 10 CSS px above it (a field with no scroller between it and a fixed container FR9 leaves to the app keeps the browser's own reveal and is not a failure; a field that a scroller holds inside such a container, left under the keyboard, is a failure), a field in an app's docked bar whose bar's bottom does not meet the keyboard's top, scroll range left at the scroller's end after the keyboard hides, a page pan or translate, a reveal later than the frame the keyboard is reported in, or a second offset inside a host that already applies the height                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
diff --git a/packages/cli/assets/docs/browser-support.doc.mjs b/packages/cli/assets/docs/browser-support.doc.mjs
index 37904e3e06b92..60569e35d4139 100644
--- a/packages/cli/assets/docs/browser-support.doc.mjs
+++ b/packages/cli/assets/docs/browser-support.doc.mjs
@@ -148,7 +148,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "On a phone, the components that respond to the on-screen keyboard, a fully expanded `height='tall'` BottomSheet and ChatLayout's composer, measure it the same way: the layout viewport's height minus the visual viewport's height times its scale. Where the visual viewport shrinks for the keyboard, as in Safari on iOS in the browser and as a home-screen app, in Firefox for Android and in Chrome on Android, they keep the focused field and the surface around it above the keyboard and leave the page where it was. If Firefox for Android pans to the field, they put the page back within a couple of frames. One exception applies when ChatLayout's scrollRef names the document. Safari on iOS then reveals the composer itself and keeps its focus. In another browser without the VirtualKeyboard API, the first keyboard show waits for the keyboard to settle before the composer rises.",
+          text: "On a phone, the components that respond to the on-screen keyboard, a fully expanded `height='tall'` BottomSheet and ChatLayout's composer, measure it the same way: the layout viewport's height minus the visual viewport's height times its scale. Where the visual viewport shrinks for the keyboard, as in Safari on iOS in the browser and as a home-screen app, in Firefox for Android and in Chrome on Android, they keep the focused field and the surface around it above the keyboard and leave the page where it was. If Firefox for Android pans to the field, they put the page back within a couple of frames. One exception applies when ChatLayout's scrollRef names the document. Safari on iOS then reveals the composer itself and keeps its focus. In another browser without the VirtualKeyboard API, the first keyboard show that leaves the composer covered waits a short time before the composer rises.",
         },
         {
           type: 'prose',
diff --git a/packages/core/src/Chat/ChatLayout.doc.mjs b/packages/core/src/Chat/ChatLayout.doc.mjs
index 4d707e416ca7f..19d6becaeabec 100644
--- a/packages/core/src/Chat/ChatLayout.doc.mjs
+++ b/packages/core/src/Chat/ChatLayout.doc.mjs
@@ -6,7 +6,7 @@ export const docs = {
   name: 'ChatLayout',
   subComponentOf: 'Chat',
   displayName: 'Chat Layout',
-  description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Set density (compact/balanced/spacious) to control spacing, message max-width, and blur layer sizing. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body. Where the visual viewport shrinks for the software keyboard, the composer stays on top of the keyboard, and a conversation at its newest message stays there. In Chrome on Android the composer rides Gboard\u2019s slides in step with them. In Safari on iOS (in the browser and as a home-screen app) and in Firefox for Android, it moves above the keyboard once the browser reports it. On a touch screen, in a top-level page, every way into the composer\u2019s text (a tap, the keyboard\u2019s previous and next buttons, Tab, the input\u2019s focus()) focuses it without scrolling the page; under a mouse or inside an iframe the browser\u2019s own focus applies. When scrollRef names the document, Safari on iOS reveals the composer itself, in the browser and as a home-screen app. Done then rests focus on no composer group. In another browser without the VirtualKeyboard API, the first keyboard show keeps the browser\u2019s focus, and the composer rises once the keyboard settles. Later shows work as elsewhere. Where your page sets interactive-widget=resizes-content, Chrome on Android shrinks the page for the keyboard itself and the composer stays above it without moving (see the browser-support guide).',
+  description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Set density (compact/balanced/spacious) to control spacing, message max-width, and blur layer sizing. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body. Where the visual viewport shrinks for the software keyboard, the composer stays on top of the keyboard, and a conversation at its newest message stays there. In Chrome on Android the composer rides Gboard\u2019s slides in step with them. In Safari on iOS (in the browser and as a home-screen app) and in Firefox for Android, it moves above the keyboard once the browser reports it. On a touch screen, in a top-level page, every way into the composer\u2019s text (a tap, the keyboard\u2019s previous and next buttons, Tab, the input\u2019s focus()) focuses it without scrolling the page; under a mouse or inside an iframe the browser\u2019s own focus applies. When scrollRef names the document, Safari on iOS reveals the composer itself, in the browser and as a home-screen app. Done then rests focus on no composer group. In another browser without the VirtualKeyboard API, each keyboard show keeps the browser\u2019s focus until one leaves the composer covered. The composer then rises after a short wait, and later shows work as elsewhere. Where your page sets interactive-widget=resizes-content, Chrome on Android shrinks the page for the keyboard itself and the composer stays above it without moving (see the browser-support guide).',
   props: [
     {
       name: 'children',
@@ -107,7 +107,7 @@ export const docs = {
       {
         name: 'Composer',
         required: true,
-        description: 'The input area for sending messages, typically ChatComposer. Docked at the bottom inside the frosted glass layer. In a top-level page on a touch screen, its wrapper (without the scroll button) is a group with no name. When the keyboard\u2019s Done ends typing, focus rests on that group (it is no tab stop), so the next tap or Tab starts from the composer. It shows the focus ring after keyboard input only. Under a mouse or inside an iframe, the wrapper is a plain container. So it is when scrollRef names the document in Safari on iOS, and at a page\u2019s first keyboard show in another browser without the VirtualKeyboard API: the browser keeps focus there.',
+        description: 'The input area for sending messages, typically ChatComposer. Docked at the bottom inside the frosted glass layer. In a top-level page on a touch screen, its wrapper (without the scroll button) is a group with no name. When the keyboard\u2019s Done ends typing, focus rests on that group (it is no tab stop), so the next tap or Tab starts from the composer. It shows the focus ring after keyboard input only. Under a mouse or inside an iframe, the wrapper is a plain container. So it is when scrollRef names the document in Safari on iOS, and in another browser without the VirtualKeyboard API until a keyboard show leaves the composer covered: the browser keeps focus there.',
       },
       {
         name: 'Empty state',
@@ -121,7 +121,7 @@ export const docs = {
 export const docsZh = {
   name: 'ChatLayout',
   displayName: 'Chat Layout',
-  description: '完整聊天界面的布局外壳。消息在页面中自然流动，编写器固定在底部，带有毛玻璃效果。通过 density 属性控制密度。在可视视口会随软键盘缩小的浏览器中，编写器停在键盘上方，停留在最新消息的对话保持在最新消息。在 Android 上的 Chrome 中，编写器随 Gboard 的滑动同步移动。在 iOS 上的 Safari（浏览器中和添加到主屏幕的网页应用）和 Android 上的 Firefox 中，编写器会在浏览器报告键盘后移到键盘上方。在触摸屏上的顶层页面中，进入编写器文本的每种方式（轻点、键盘的上一项和下一项按钮、Tab、输入框的 focus()）都会聚焦它而不滚动页面；使用鼠标或在 iframe 中时沿用浏览器自身的聚焦行为。当 scrollRef 指向文档时，iOS 上的 Safari（浏览器中和主屏幕网页应用）会自行将编写器显示在键盘上方，键盘的“完成”也不会把焦点停在编写器分组上。在其他没有 VirtualKeyboard API 的浏览器中，第一次弹出键盘时沿用浏览器自身的聚焦，编写器会在键盘稳定后升到键盘上方；之后的弹出与其他情况相同。如果页面设置了 interactive-widget=resizes-content，Android 上的 Chrome 会自行为键盘缩小页面，编写器停在键盘上方而不移动（参见浏览器支持指南）。',
+  description: '完整聊天界面的布局外壳。消息在页面中自然流动，编写器固定在底部，带有毛玻璃效果。通过 density 属性控制密度。在可视视口会随软键盘缩小的浏览器中，编写器停在键盘上方，停留在最新消息的对话保持在最新消息。在 Android 上的 Chrome 中，编写器随 Gboard 的滑动同步移动。在 iOS 上的 Safari（浏览器中和添加到主屏幕的网页应用）和 Android 上的 Firefox 中，编写器会在浏览器报告键盘后移到键盘上方。在触摸屏上的顶层页面中，进入编写器文本的每种方式（轻点、键盘的上一项和下一项按钮、Tab、输入框的 focus()）都会聚焦它而不滚动页面；使用鼠标或在 iframe 中时沿用浏览器自身的聚焦行为。当 scrollRef 指向文档时，iOS 上的 Safari（浏览器中和主屏幕网页应用）会自行将编写器显示在键盘上方，键盘的“完成”也不会把焦点停在编写器分组上。在其他没有 VirtualKeyboard API 的浏览器中，每次弹出键盘都沿用浏览器自身的聚焦，直到某次弹出让编写器被键盘遮住；编写器会在短暂等待后升到键盘上方，之后的弹出与其他情况相同。如果页面设置了 interactive-widget=resizes-content，Android 上的 Chrome 会自行为键盘缩小页面，编写器停在键盘上方而不移动（参见浏览器支持指南）。',
   propDescriptions: {
     children: '消息内容，通常是 ChatMessageList。在页面中自然流动。',
     composer: '编写器元素，通常是 ChatComposer。固定在底部，带有毛玻璃底座。',
@@ -135,7 +135,7 @@ export const docsZh = {
 export const docsDense = {
   name: 'ChatLayout',
   displayName: 'Chat Layout',
-  description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; density prop (default balanced); scrollRef delegates to parent/body; in Chrome on Android (Gboard) the composer rides the software keyboard in step; in Safari on iOS and Firefox for Android it moves above the keyboard once reported (Chrome with interactive-widget=resizes-content: the page resizes, no move); transcript stays at newest msg, on a touch screen in a top-level page every focus route (tap, prev/next, Tab, focus()) w/o page scroll and Done rests focus on the composer group (no name, ring after keyboard input only, no tab stop); under a mouse or in an iframe: plain wrapper, browser focus; scrollRef on the document in Safari on iOS: Safari reveals the composer, browser focus, no group; other browsers without the VirtualKeyboard API: the first keyboard show rises once settled',
+  description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; density prop (default balanced); scrollRef delegates to parent/body; in Chrome on Android (Gboard) the composer rides the software keyboard in step; in Safari on iOS and Firefox for Android it moves above the keyboard once reported (Chrome with interactive-widget=resizes-content: the page resizes, no move); transcript stays at newest msg, on a touch screen in a top-level page every focus route (tap, prev/next, Tab, focus()) w/o page scroll and Done rests focus on the composer group (no name, ring after keyboard input only, no tab stop); under a mouse or in an iframe: plain wrapper, browser focus; scrollRef on the document in Safari on iOS: Safari reveals the composer, browser focus, no group; other browsers without the VirtualKeyboard API: browser focus until a show leaves the composer covered, which rises after a short wait',
   usage: {
     bestPractices: [
       {guidance: true, description: 'Pass ChatMessageList as children and ChatComposer as composer prop for complete chat.'},
diff --git a/packages/core/src/Chat/useChatKeyboard.test.tsx b/packages/core/src/Chat/useChatKeyboard.test.tsx
index 1665c496385f9..79eda9a62226c 100644
--- a/packages/core/src/Chat/useChatKeyboard.test.tsx
+++ b/packages/core/src/Chat/useChatKeyboard.test.tsx
@@ -29,7 +29,7 @@ import {__resetInteractionModalityForTest} from '../utils/interactionModality';
 import {
   __focusTakeoverCallersForTest,
   __resetDockRevealForTest,
-  getDockReveal,
+  isDockLeftCovered,
 } from '../keyboard/keyboardHeight';
 
 // jsdom dates events on the epoch clock, but a browser dates them on
@@ -437,8 +437,8 @@ describe('ChatLayout in a page that scrolls the document', () => {
     });
     return end.defaultPrevented;
   }
-  // A first keyboard show the dock stays covered at, then the keyboard goes:
-  // the page has learned that its browser does not pan to the dock.
+  // A first keyboard show where the dock stays covered, then a hide. The page
+  // then knows that its browser does not pan to the dock.
   function learnCovered() {
     report(window.innerHeight - 290);
     wait(800);
@@ -470,7 +470,7 @@ describe('ChatLayout in a page that scrolls the document', () => {
     wait(3000);
     expect(layoutLift(dockOf(container))).toBe(0);
     expect(keyboardRoom(messagesOf())).toBe(0);
-    expect(getDockReveal(window)).toBe(true);
+    expect(isDockLeftCovered(window)).toBe(false);
   });
 
   it('lifts nothing while the browser may still pan, then lifts by the cover 0.7 s after the keyboard\u2019s report, as in Firefox for Android', () => {
@@ -481,7 +481,7 @@ describe('ChatLayout in a page that scrolls the document', () => {
     wait(50);
     expect(layoutLift(dockOf(container))).toBe(290);
     expect(keyboardRoom(messagesOf())).toBe(290);
-    expect(getDockReveal(window)).toBe(false);
+    expect(isDockLeftCovered(window)).toBe(true);
   });
 
   it('keeps the 0.7 s wait through the height reports of the keyboard\u2019s slide, then follows the keyboard\u2019s height', () => {
@@ -517,17 +517,59 @@ describe('ChatLayout in a page that scrolls the document', () => {
     pan(337);
     wait(3000);
     expect(layoutLift(dockOf(container))).toBe(0);
-    expect(getDockReveal(window)).toBe(true);
+    expect(isDockLeftCovered(window)).toBe(false);
     expect(__focusTakeoverCallersForTest(document)).toBe(0);
   });
 
+  it('lets a pan to the dock decide only its show, as Firefox\u2019s at 108 ms: the next show it leaves covered rises at 0.7 s and teaches the page, and the one after rises at once', () => {
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    wait(108);
+    pan(290);
+    wait(3000);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    expect(isDockLeftCovered(window)).toBe(false);
+    expect(__focusTakeoverCallersForTest(document)).toBe(0);
+    report(window.innerHeight);
+    pan(0);
+    report(window.innerHeight - 290);
+    wait(699);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    wait(1);
+    expect(layoutLift(dockOf(container))).toBe(290);
+    expect(isDockLeftCovered(window)).toBe(true);
+    report(window.innerHeight);
+    report(window.innerHeight - 290);
+    expect(layoutLift(dockOf(container))).toBe(290);
+  });
+
+  it('never lifts and never learns in Safari, which pans to the dock at every show', () => {
+    const {container} = renderDocumentLayout();
+    for (const panAt of [46, 0, 384]) {
+      if (panAt === 0) {
+        viewport.offsetTop = 337;
+        report(window.innerHeight - 337);
+      } else {
+        report(window.innerHeight - 337);
+        wait(panAt);
+        pan(337);
+      }
+      wait(3000);
+      expect(layoutLift(dockOf(container))).toBe(0);
+      expect(isDockLeftCovered(window)).toBe(false);
+      expect(__focusTakeoverCallersForTest(document)).toBe(0);
+      report(window.innerHeight);
+      pan(0);
+    }
+  });
+
   it('lifts nothing, and learns nothing, when the dock is revealed at the report with no pan', () => {
     viewport.offsetTop = 337;
     const {container} = renderDocumentLayout();
     report(window.innerHeight - 337);
     wait(3000);
     expect(layoutLift(dockOf(container))).toBe(0);
-    expect(getDockReveal(window)).toBeUndefined();
+    expect(isDockLeftCovered(window)).toBe(false);
   });
 
   it('lifts at the 3 s cap when pans keep restarting the wait, and learns nothing from that show', () => {
@@ -538,7 +580,7 @@ describe('ChatLayout in a page that scrolls the document', () => {
       pan(i % 2 === 1 ? 10 : 0);
     }
     expect(layoutLift(dockOf(container))).toBeGreaterThanOrEqual(290);
-    expect(getDockReveal(window)).toBeUndefined();
+    expect(isDockLeftCovered(window)).toBe(false);
     report(window.innerHeight);
     expect(layoutLift(dockOf(container))).toBe(0);
   });
@@ -565,7 +607,7 @@ describe('ChatLayout in a page that scrolls the document', () => {
     wait(3000);
     expect(layoutLift(dockOf(container))).toBe(0);
     expect(__focusTakeoverCallersForTest(document)).toBe(0);
-    expect(getDockReveal(window)).toBe(true);
+    expect(isDockLeftCovered(window)).toBe(false);
   });
 
   it('drops the lift once for a slow browser whose pan to the dock comes after the wait, with no input since the show opened', () => {
@@ -575,7 +617,7 @@ describe('ChatLayout in a page that scrolls the document', () => {
     expect(layoutLift(dockOf(container))).toBe(337);
     pan(337);
     expect(layoutLift(dockOf(container))).toBe(0);
-    expect(getDockReveal(window)).toBe(true);
+    expect(isDockLeftCovered(window)).toBe(false);
     expect(__focusTakeoverCallersForTest(document)).toBe(0);
   });
 
@@ -586,7 +628,7 @@ describe('ChatLayout in a page that scrolls the document', () => {
     drag();
     pan(290);
     expect(layoutLift(dockOf(container))).toBe(290);
-    expect(getDockReveal(window)).toBe(false);
+    expect(isDockLeftCovered(window)).toBe(true);
   });
 
   it('keeps the lift for a reveal-sized pan after a wheel', () => {
@@ -608,7 +650,58 @@ describe('ChatLayout in a page that scrolls the document', () => {
     report(window.innerHeight - 280);
     pan(280);
     expect(layoutLift(dockOf(container))).toBe(280);
-    expect(getDockReveal(window)).toBe(false);
+    expect(isDockLeftCovered(window)).toBe(true);
+  });
+
+  it('learns nothing from a show with a touch in the wait, as a second tap before Safari\u2019s pan, and keeps that pan', () => {
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 337);
+    wait(20);
+    drag();
+    wait(26);
+    pan(337);
+    wait(3000);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    expect(isDockLeftCovered(window)).toBe(false);
+    report(window.innerHeight);
+    pan(0);
+    // The next show decides by its own pan, and learns nothing either.
+    report(window.innerHeight - 337);
+    wait(46);
+    pan(337);
+    expect(isDockLeftCovered(window)).toBe(false);
+    expect(layoutLift(dockOf(container))).toBe(0);
+  });
+
+  it('keeps Safari\u2019s pan that came before a later tap', () => {
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 337);
+    wait(46);
+    pan(337);
+    wait(254);
+    drag();
+    wait(3000);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    expect(isDockLeftCovered(window)).toBe(false);
+  });
+
+  it('lifts a dock still covered at the wait\u2019s end after a touch in the wait, and learns nothing from that show', () => {
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    wait(100);
+    drag();
+    wait(599);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    wait(1);
+    expect(layoutLift(dockOf(container))).toBe(290);
+    expect(isDockLeftCovered(window)).toBe(false);
+    report(window.innerHeight);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    // The next show, with no input, learns that the dock stays covered.
+    report(window.innerHeight - 290);
+    wait(700);
+    expect(isDockLeftCovered(window)).toBe(true);
+    expect(layoutLift(dockOf(container))).toBe(290);
   });
 
   it('keeps the lift for a pan smaller than the cover', () => {
@@ -625,7 +718,7 @@ describe('ChatLayout in a page that scrolls the document', () => {
     report(window.innerHeight - 290);
     pan(290);
     expect(layoutLift(dockOf(container))).toBe(290);
-    expect(getDockReveal(window)).toBe(false);
+    expect(isDockLeftCovered(window)).toBe(true);
   });
 
   it('keeps the lift at a show that reached the cap when a touch came before the pan', () => {
@@ -717,8 +810,8 @@ describe('ChatLayout in a page that scrolls the document', () => {
     try {
       renderDocumentLayout();
       learnCovered();
-      expect(getDockReveal(window)).toBe(false);
-      expect(getDockReveal(frame.contentWindow!)).toBeUndefined();
+      expect(isDockLeftCovered(window)).toBe(true);
+      expect(isDockLeftCovered(frame.contentWindow!)).toBe(false);
     } finally {
       frame.remove();
     }
@@ -750,7 +843,7 @@ describe('ChatLayout in a page that scrolls the document', () => {
       expect(__focusTakeoverCallersForTest(document)).toBe(1);
       report(window.innerHeight - 300);
       expect(layoutLift(dockOf(container))).toBe(300);
-      expect(getDockReveal(window)).toBeUndefined();
+      expect(isDockLeftCovered(window)).toBe(false);
     } finally {
       scroller.remove();
     }
@@ -768,7 +861,7 @@ describe('ChatLayout in a page that scrolls the document', () => {
     expect(layoutLift(dockOf(container))).toBe(300);
     expect(keyboardRoom(messagesOf())).toBe(300);
     pan(300);
-    expect(getDockReveal(window)).toBeUndefined();
+    expect(isDockLeftCovered(window)).toBe(false);
     expect(__focusTakeoverCallersForTest(document)).toBe(1);
   });
 });
diff --git a/packages/core/src/Chat/useChatKeyboard.ts b/packages/core/src/Chat/useChatKeyboard.ts
index 6582bc5f14c4d..462bbbb8c338a 100644
--- a/packages/core/src/Chat/useChatKeyboard.ts
+++ b/packages/core/src/Chat/useChatKeyboard.ts
@@ -29,9 +29,9 @@ import {createMotionEngine, type Animator} from '../motion/animator';
 import {
   claimTapFocus,
   findTextEntryControl,
-  getDockReveal,
   getDockRevealVersion,
   getKeyboardHeight,
+  isDockLeftCovered,
   isDockShowCovered,
   isTextEntryControl,
   refuseFocusReveal,
@@ -543,11 +543,11 @@ function isUnguidedDocument(win: Window, scroller: Element | null): boolean {
  * that scrolls the document, in a browser with no layout guide. It holds
  * until a keyboard show finds the fixed dock left covered. Safari on iOS pans
  * the visual viewport to the dock, and a lift would add to that pan. Firefox
- * for Android leaves it covered: from then on, the layout keeps the composer
- * above the keyboard itself.
+ * for Android can leave it covered: from then on, the layout keeps the
+ * composer above the keyboard itself.
  */
 function leavesRevealToBrowser(win: Window, scroller: Element | null): boolean {
-  return isUnguidedDocument(win, scroller) && getDockReveal(win) !== false;
+  return isUnguidedDocument(win, scroller) && !isDockLeftCovered(win);
 }
 
 // The document's root and body both scroll the page.
diff --git a/packages/core/src/keyboard/README.md b/packages/core/src/keyboard/README.md
index 7ac3fa02b2f00..9a48e6aea9f53 100644
--- a/packages/core/src/keyboard/README.md
+++ b/packages/core/src/keyboard/README.md
@@ -73,13 +73,15 @@ that times motion with it. Everything here is internal to
   each height the module reports: the keyboard targets and ChatLayout's
   composer watch with it. With `dock` (off by default), the watch also
   decides once per keyboard show whether the browser pans the visual viewport
-  to a fixed dock in a page that scrolls the document. A pan marks a browser
-  that reveals the dock: no pan is put back. A dock still covered 0.7 s after
-  the show's opening report marks one that does not. Only a pan restarts that
-  wait, up to 3 s; the height reports of the keyboard's slide do not.
-  `getDockReveal(win)` keeps that per window, and `getKeyboardPan(win)` gives
-  the pan read with each report. Only a touch or a wheel since the show's
-  opening report closes the late-pan check; no later report reopens it.
+  to a fixed dock in a page that scrolls the document. A pan to the dock
+  decides only its own show: no lift, and no pan is put back. A dock still
+  covered 0.7 s after the show's opening report rises. Only a pan restarts
+  that wait, up to 3 s; the height reports of the keyboard's slide do not.
+  With no touch or wheel in the wait, the page then learns that its browser
+  leaves the dock covered (`isDockLeftCovered(win)`), and every later show
+  lifts at once. A show with a touch or a wheel in the wait learns nothing. A
+  late pan to the dock after the lift, before any input, drops the lift and
+  forgets it. `getKeyboardPan(win)` gives the pan read with each report.
 - **Keyboard targets (`keyboardTarget.ts`):** a target keeps the focused field
   inside it above the keyboard, and registers so a field inside moves nothing
   itself (`registerKeyboardTarget`, `isInsideKeyboardTarget`).
diff --git a/packages/core/src/keyboard/keyboardHeight.ts b/packages/core/src/keyboard/keyboardHeight.ts
index 993f0bf83619d..c63688998d2ed 100644
--- a/packages/core/src/keyboard/keyboardHeight.ts
+++ b/packages/core/src/keyboard/keyboardHeight.ts
@@ -10,7 +10,7 @@
  *   isKeyboardMeasurable, hasVirtualKeyboard, subscribeKeyboardHeight,
  *   getKeyboardHeight, getKeyboardPan, isTextEntryControl,
  *   findTextEntryControl, refuseFocusReveal and watchRevealPan. It also keeps
- *   what a window's browser does with a fixed dock (getDockReveal)
+ *   whether a window's browser leaves a fixed dock covered (isDockLeftCovered)
  * @position Core's one source for the on-screen keyboard. It is internal to
  *   core and never exported from the package.
  *
@@ -490,7 +490,7 @@ export interface WatchRevealPanOptions {
   /**
    * The field sits in a fixed dock of a page that scrolls the document. Each
    * keyboard show then decides once whether the browser pans the visual
-   * viewport to the dock (getDockReveal). Off by default.
+   * viewport to the dock (isDockLeftCovered). Off by default.
    * @default false
    */
   dock?: boolean;
@@ -599,11 +599,12 @@ function watchWheels(doc: Document, onWheel: () => void): () => void {
 const DOCK_REVEAL_SETTLE_MS = 700;
 const DOCK_REVEAL_CAP_MS = 3000;
 
-// What each window's browser did with a fixed dock at a keyboard show. True:
-// it panned the visual viewport to the dock. False: the dock stayed covered.
-const dockReveals = new WeakMap<Window, boolean>();
-// The windows whose current show found the dock covered at the wait's cap.
-// Such a show lifts the dock but teaches nothing.
+// The windows whose browser left a fixed dock covered at a keyboard show with
+// no touch or wheel in the wait.
+const docksLeftCovered = new WeakSet<Window>();
+// The windows whose current show found the dock covered without learning it.
+// That is at the wait's cap, or after a touch or a wheel in the wait. Such a
+// show lifts the dock but teaches nothing.
 const coveredShows = new WeakSet<Window>();
 const dockRevealListeners = new Set<() => void>();
 let dockRevealVersion = 0;
@@ -615,28 +616,33 @@ function notifyDockReveal(): void {
   }
 }
 
-function learnDockReveal(win: Window, pans: boolean): void {
-  if (dockReveals.get(win) !== pans) {
-    dockReveals.set(win, pans);
+function learnDockLeftCovered(win: Window, covered: boolean): void {
+  if (docksLeftCovered.has(win) !== covered) {
+    if (covered) {
+      docksLeftCovered.add(win);
+    } else {
+      docksLeftCovered.delete(win);
+    }
     notifyDockReveal();
   }
 }
 
 /**
- * What `win`'s browser was found to do with a fixed dock at a keyboard show.
- * True: it pans the visual viewport to the dock. False: it leaves the dock
- * covered. Undefined until a reveal-pan watch with `dock` decides it.
+ * Whether `win`'s browser was found to leave a fixed dock covered at a
+ * keyboard show. A pan to the dock decides only its own show and teaches
+ * nothing. A browser can pan at one show and not at the next. A late pan to
+ * the dock after the lift, before any input, forgets it.
  */
-export function getDockReveal(win: Window): boolean | undefined {
-  return dockReveals.get(win);
+export function isDockLeftCovered(win: Window): boolean {
+  return docksLeftCovered.has(win);
 }
 
 /** Whether the fixed dock in `win` stays covered at this keyboard show. */
 export function isDockShowCovered(win: Window): boolean {
-  return dockReveals.get(win) === false || coveredShows.has(win);
+  return docksLeftCovered.has(win) || coveredShows.has(win);
 }
 
-/** Calls `listener` when getDockReveal or isDockShowCovered changes. */
+/** Calls `listener` when isDockLeftCovered or isDockShowCovered changes. */
 export function subscribeDockReveal(listener: () => void): () => void {
   dockRevealListeners.add(listener);
   return () => {
@@ -656,24 +662,23 @@ export function getDockRevealVersion(): number {
  * @internal
  */
 export function __resetDockRevealForTest(win: Window): void {
-  const known = dockReveals.delete(win);
+  const known = docksLeftCovered.delete(win);
   if (coveredShows.delete(win) || known) {
     notifyDockReveal();
   }
 }
 
-// The dock's watch: one decision per keyboard show. A pan to the dock marks
-// a browser that reveals it. A dock still covered when the wait ends marks
-// one that does not, and the dock rises. Only the show that
-// learned that, with no touch or wheel since its opening report, still meets
-// a slow browser's pan: the lift then goes.
+// The dock's watch: one decision per keyboard show. A pan to the dock decides
+// that show alone: no lift. A dock still covered when the wait ends rises.
+// With no touch or wheel in the wait, the page learns that its browser leaves
+// the dock covered. Only the show that learned it, before any input, still
+// meets a slow browser's pan: the lift then goes, and the page forgets it.
 function watchDock(win: Window): {
   report: (height: number) => boolean;
   input: () => void;
   stop: () => void;
 } {
   let show: 'none' | 'watching' | 'revealed' | 'covered' = 'none';
-  let restPan = getKeyboardPan(win) ?? 0;
   let lastPan = getKeyboardPan(win);
   let coveredPan = 0;
   let isClassifying = false;
@@ -691,22 +696,33 @@ function watchDock(win: Window): {
       capTimer = null;
     }
   };
-  // A pan that reveals the dock before any input: with no lift, the dock
-  // would rest at or above the visual viewport's bottom.
+  // With no lift, the dock rests at or above the visual viewport's bottom.
+  const isRevealed = (pan: number | null, height: number): pan is number =>
+    pan != null && pan >= height - 1;
+  // A pan the browser made before any input of the show.
   const isRevealPan = (pan: number | null, height: number): pan is number =>
-    pan != null && !inputSinceShow && pan >= height - 1;
+    !inputSinceShow && isRevealed(pan, height);
   const cover = (learn: boolean) => {
     clearTimers();
     show = 'covered';
     coveredPan = getKeyboardPan(win) ?? 0;
     if (learn) {
       isClassifying = true;
-      learnDockReveal(win, false);
+      learnDockLeftCovered(win, true);
     } else {
       coveredShows.add(win);
       notifyDockReveal();
     }
   };
+  // Where the dock rests when the wait ends decides the show.
+  const settle = () => {
+    if (isRevealed(getKeyboardPan(win), getKeyboardHeight(win))) {
+      clearTimers();
+      show = 'revealed';
+    } else {
+      cover(!inputSinceShow);
+    }
+  };
   const restartSettle = () => {
     if (settleTimer != null) {
       clearTimeout(settleTimer);
@@ -714,7 +730,7 @@ function watchDock(win: Window): {
     settleTimer = setTimeout(() => {
       settleTimer = null;
       if (show === 'watching') {
-        cover(true);
+        settle();
       }
     }, DOCK_REVEAL_SETTLE_MS);
   };
@@ -733,25 +749,19 @@ function watchDock(win: Window): {
       clearTimers();
       show = 'none';
       isClassifying = false;
-      restPan = pan ?? 0;
       if (coveredShows.delete(win)) {
         notifyDockReveal();
       }
-      return dockReveals.get(win) !== false;
+      return !docksLeftCovered.has(win);
     }
     if (show === 'none') {
       inputSinceShow = false;
-      if (dockReveals.get(win) === false) {
+      if (docksLeftCovered.has(win)) {
         show = 'covered';
         return false;
       }
-      if (pan != null && pan >= height - 1) {
-        // Revealed at the report. Only a pan there shows what the browser
-        // does; a show that needed none teaches nothing.
+      if (isRevealed(pan, height)) {
         show = 'revealed';
-        if (pan > restPan + 0.5) {
-          learnDockReveal(win, true);
-        }
         return true;
       }
       show = 'watching';
@@ -765,10 +775,9 @@ function watchDock(win: Window): {
       return true;
     }
     if (show === 'watching') {
-      if (isRevealPan(pan, height) && pan > restPan + 0.5) {
+      if (isRevealPan(pan, height)) {
         clearTimers();
         show = 'revealed';
-        learnDockReveal(win, true);
       } else if (panned) {
         restartSettle();
       }
@@ -778,8 +787,12 @@ function watchDock(win: Window): {
       if (isRevealPan(pan, height) && pan > coveredPan + 0.5) {
         show = 'revealed';
         isClassifying = false;
-        coveredShows.delete(win);
-        learnDockReveal(win, true);
+        const wasCoveredShow = coveredShows.delete(win);
+        if (docksLeftCovered.has(win)) {
+          learnDockLeftCovered(win, false);
+        } else if (wasCoveredShow) {
+          notifyDockReveal();
+        }
       }
       return true;
     }

From df30dc50e02cd42bfef345da06af060c2a2b8500 Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 8 Nov 2026 13:00:23 -0800
Subject: [PATCH 09/16] fix(ChatLayout): the 3 s cap decides by where the dock
 rests

A wait that pans kept restarting ended at the cap with a lift, even
when the browser's last pan had revealed the dock by then. The cap
now makes the same check as the wait's own end, and still teaches
the page nothing.
---
 packages/core/src/Chat/useChatKeyboard.test.tsx | 16 ++++++++++++++++
 packages/core/src/keyboard/keyboardHeight.ts    | 11 ++++++-----
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/packages/core/src/Chat/useChatKeyboard.test.tsx b/packages/core/src/Chat/useChatKeyboard.test.tsx
index 79eda9a62226c..f25b08a8aa987 100644
--- a/packages/core/src/Chat/useChatKeyboard.test.tsx
+++ b/packages/core/src/Chat/useChatKeyboard.test.tsx
@@ -721,6 +721,22 @@ describe('ChatLayout in a page that scrolls the document', () => {
     expect(isDockLeftCovered(window)).toBe(true);
   });
 
+  it('lifts nothing at the 3 s cap when the dock is revealed by then', () => {
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    for (let i = 1; i <= 5; i += 1) {
+      wait(500);
+      pan(i * 10);
+    }
+    // Late input keeps the last pan from deciding the show at once.
+    drag();
+    wait(400);
+    pan(290);
+    wait(100);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    expect(isDockLeftCovered(window)).toBe(false);
+  });
+
   it('keeps the lift at a show that reached the cap when a touch came before the pan', () => {
     const {container} = renderDocumentLayout();
     report(window.innerHeight - 290);
diff --git a/packages/core/src/keyboard/keyboardHeight.ts b/packages/core/src/keyboard/keyboardHeight.ts
index c63688998d2ed..3371d9f4c2d43 100644
--- a/packages/core/src/keyboard/keyboardHeight.ts
+++ b/packages/core/src/keyboard/keyboardHeight.ts
@@ -714,13 +714,14 @@ function watchDock(win: Window): {
       notifyDockReveal();
     }
   };
-  // Where the dock rests when the wait ends decides the show.
-  const settle = () => {
+  // Where the dock rests when the wait ends decides the show. Only a clean
+  // wait that ends on its own teaches the page.
+  const settle = (atCap: boolean) => {
     if (isRevealed(getKeyboardPan(win), getKeyboardHeight(win))) {
       clearTimers();
       show = 'revealed';
     } else {
-      cover(!inputSinceShow);
+      cover(!atCap && !inputSinceShow);
     }
   };
   const restartSettle = () => {
@@ -730,7 +731,7 @@ function watchDock(win: Window): {
     settleTimer = setTimeout(() => {
       settleTimer = null;
       if (show === 'watching') {
-        settle();
+        settle(false);
       }
     }, DOCK_REVEAL_SETTLE_MS);
   };
@@ -768,7 +769,7 @@ function watchDock(win: Window): {
       capTimer = setTimeout(() => {
         capTimer = null;
         if (show === 'watching') {
-          cover(false);
+          settle(true);
         }
       }, DOCK_REVEAL_CAP_MS);
       restartSettle();

From 714141ef234ca8ceb70669df3fcd2711de41716c Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 8 Nov 2026 13:35:23 -0800
Subject: [PATCH 10/16] fix(ChatLayout): the dock follows the cover the pan
 leaves

When the browser keeps the reveal, the fixed dock now rises by the
part of the keyboard's cover that the visual viewport's pan leaves.
It holds still while the browser's own reveal runs. After a touch
or a wheel, it follows that part as a scroll moves the pan, so a
reader's scroll after Firefox's own pan keeps the composer on the
keyboard. A show for a field outside the dock decides nothing and
follows the part left from the start.

Where the layout viewport's height follows the pan, as in Safari on
iOS, the dock holds for the rest of the show: a lift there makes the
browser reveal the focused composer again. Each keyboard report now
carries the keyboard's cover of the initial containing block, read
with the same visual-viewport read. The wheel gate uses the shared
input stream directly.
---
 ...-layout-document-scroll-safari-keyboard.md |   2 +-
 docs/specs/AST-099-mobile-keyboard/spec.md    |  52 +++--
 .../core/src/Chat/useChatKeyboard.test.tsx    | 181 ++++++++++++++-
 packages/core/src/Chat/useChatKeyboard.ts     |  28 ++-
 packages/core/src/keyboard/README.md          |  24 +-
 .../core/src/keyboard/keyboardHeight.test.ts  |   2 +-
 packages/core/src/keyboard/keyboardHeight.ts  | 214 +++++++++++-------
 7 files changed, 373 insertions(+), 130 deletions(-)

diff --git a/.changeset/chat-layout-document-scroll-safari-keyboard.md b/.changeset/chat-layout-document-scroll-safari-keyboard.md
index b943d7d3626eb..92e0d08e2b55a 100644
--- a/.changeset/chat-layout-document-scroll-safari-keyboard.md
+++ b/.changeset/chat-layout-document-scroll-safari-keyboard.md
@@ -3,5 +3,5 @@
 '@astryxdesign/cli': patch
 ---
 
-[fix] **ChatLayout**: In a page that scrolls the document (`scrollRef`), the composer stays right above the software keyboard in Safari on iOS, instead of jumping under the status bar. In Firefox for Android, the first keyboard show on each page covers the composer for up to about 0.7 s before it rises.
+[fix] **ChatLayout**: In a page that scrolls the document (`scrollRef`), the composer stays right above the software keyboard in Safari on iOS, instead of jumping under the status bar. In Firefox for Android, the first keyboard show on each page that leaves the composer covered keeps it covered for about 0.75 s on a slow device before it rises.
 @vjeux
diff --git a/docs/specs/AST-099-mobile-keyboard/spec.md b/docs/specs/AST-099-mobile-keyboard/spec.md
index bbc6ddf391df0..ec2c2487607a1 100644
--- a/docs/specs/AST-099-mobile-keyboard/spec.md
+++ b/docs/specs/AST-099-mobile-keyboard/spec.md
@@ -104,13 +104,17 @@ app to turn on.
   ChatLayout's `scrollRef` names the document's scroller, Safari on iOS, in the
   browser and as a home-screen app, pans the visual viewport to the fixed dock
   and keeps the pan. There ChatLayout leaves focus and the reveal to the
-  browser, and the dock rises nothing: the composer is not a keyboard-aware
-  surface (FR4). ChatLayout reads this from the browser's behavior at each show.
-  Without the VirtualKeyboard API, each keyboard show leaves focus to the
-  browser and watches the visual viewport, until a show finds the dock covered.
-  A show where the browser pans to the dock needs no lift. A dock still covered
-  when a bounded wait ends (Gap 16) rises by the keyboard's cover. From then on,
-  the composer is a keyboard-aware surface there, as elsewhere. FR9's
+  browser: the composer is not a keyboard-aware surface (FR4). ChatLayout reads
+  the browser's behavior at each show. Without the VirtualKeyboard API, each
+  keyboard show leaves focus to the browser until a show finds the dock covered.
+  While the browser's own reveal runs, the dock does not move (Gap 16). Then the
+  dock rises by the part of the keyboard's cover that the visual viewport's pan
+  leaves. A pan to the dock leaves none, so the dock rises nothing. After a
+  touch or a wheel, the dock follows that part as a scroll moves the pan. Where
+  the layout viewport's height follows the pan instead, as in Safari on iOS, the
+  dock does not move for the rest of that show (Gap 17). Once a show finds the
+  dock covered, the composer is a keyboard-aware surface there, as elsewhere.
+  FR9's
   docked ride is the one exception: Core moves an app's docked bar as FR9 sets
   out. How the value reaches styles is `architecture:react-component-runtime`
   INV11. Riding the keyboard's motion layers on top of that layout, so layout
@@ -215,8 +219,9 @@ app to turn on.
     height (FR2) elsewhere, such as Safari on iOS. A Core host rides by applying
     the keyboard height on its own element (FR3), and the field inside it is not
     moved a second time. FR3 names one exception: ChatLayout's dock when its
-    `scrollRef` names the document's scroller. In Safari on iOS, the browser's
-    own pan places it.
+    `scrollRef` names the document's scroller, without the VirtualKeyboard API.
+    The browser's own pan places it. The dock rises only by the part of the
+    keyboard's cover that the pan leaves, and only as FR3 says.
   - **App-owned docked containers.** A container the app owns rides too when it
     is fixed-position, does not fill the viewport, and is docked: its layout
     box, before any transform, sits at the viewport's bottom edge. A docked
@@ -393,17 +398,25 @@ No covered field meets FR9 on `main`. Each gap below is open.
   moves at that report, in one frame, instead of riding from the blur (FR3).
 - **Gap 16 — The first covered keyboard show of a document-scrolling ChatLayout
   without the VirtualKeyboard API.** ChatLayout cannot tell before a show
-  whether the browser pans to its fixed dock (FR3). So each show leaves focus to
-  the browser until one show finds the dock covered. A show where the browser
-  pans to the dock needs no lift, and teaches nothing: Firefox for Android pans
-  at some shows and not at others. In Firefox for Android, the first show it
-  leaves covered keeps the composer covered for up to about 0.7 s after the
-  keyboard's report. Only a pan of the visual viewport restarts that wait, and
-  the wait ends at 3 s at most. Every later show lifts the dock at once. A show
-  with a touch or a wheel in the wait also lifts only when the wait ends, and
-  teaches nothing. On the iOS Simulator, Safari's pan arrived 0 to 384 ms after
-  the keyboard's report. A short cover once, at Firefox's first covered show, is
+  whether the browser pans to its fixed dock (FR3). So at each show the dock
+  does not move while the browser's own reveal runs, up to a bounded wait. A pan
+  to the dock decides only that show: Firefox for Android pans at some shows and
+  not at others. In Firefox for Android, the first show the browser leaves
+  covered keeps the composer covered until the wait ends. With a slow-device
+  profile, that is about 0.75 s (731 to 755 ms). Only a pan of the visual
+  viewport restarts the wait, and the wait ends at 3 s at most. Every later show
+  lifts the dock at once. A show with a touch or a wheel in the wait teaches
+  nothing. When its wait ends, its dock follows the part of the cover that the
+  pan leaves. On the iOS Simulator, Safari's pan arrived 0 to 400 ms after the
+  keyboard's report. A short cover once, at Firefox's first covered show, is
   better than a lift and then a drop in a slow Safari.
+- **Gap 17 — Safari on iOS on a slow scroll toward the top with the keyboard
+  up.** In a page that scrolls the document, Safari on iOS unwinds its own pan
+  as the reader scrolls toward the page's top with the keyboard up. Its layout
+  viewport grows by the same steps, so ChatLayout's composer slides under the
+  keyboard, as in earlier releases. ChatLayout does not move the dock while the
+  layout viewport's height follows the pan. A lift there makes Safari reveal the
+  focused composer again, and the lift and the reveal then chase each other.
 
 ### Follow-up
 
@@ -429,6 +442,7 @@ that sets its own `translate`, to the app.
 | FR3–FR4  | ChatLayout's keyboard tests in jsdom and its interaction proofs in Chromium and WebKit                       | the fixed and the sticky dock with the keyboard shown and hidden; the message area's end padding; a transcript at its newest message; a page pinch-zoomed with the keyboard up; focus by tap, Tab, `focus()` and Done, under a finger and under a mouse                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | The dock left under the keyboard or lifted with none; the newest message unable to scroll above the composer; a transcript at its newest message left behind; the page panned to the composer's text under a finger, outside FR3's document-scroll exception; focus left in the text after Done, or the composer group focusable outside Done's park                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | FR3–FR4  | Firefox for Android in the emulator, top-level document                                                      | ChatLayout whose `scrollRef` names the document, the page's first keyboard show: a tap on the composer, the keyboard shown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Once the wait ends (Gap 16), the composer does not rest on the keyboard: its bottom sits more than 0.5 CSS px below the visual viewport's bottom                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | FR3–FR4  | Firefox for Android in the emulator, top-level document                                                      | The same page's next keyboard show after one that left the composer covered: a tap on the composer, the keyboard shown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | The composer does not rest on the keyboard at once: its bottom sits more than 0.5 CSS px below the visual viewport's bottom                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| FR3–FR4  | Firefox for Android in the emulator at normal speed, top-level document                                      | The same page after a show the browser pans to the composer: the page scrolled with the keyboard up, down and back up                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | On a settled frame, the composer leaves the keyboard: its bottom sits more than 0.5 CSS px off the visual viewport's bottom                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | FR8      | ChatLayout's interaction proofs in Chromium with Chrome's keyboard report                                    | the dock riding Gboard's slide up from the report and down from the blur; reduced motion on                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | The dock lagging Gboard's slide, laying out or painting per frame, or jumping at the hand-back; the dock travelling under reduced motion instead of DR2's cross-fade                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | FR9      | ChatLayout's keyboard tests in jsdom                                                                         | ChatComposer in the fixed and the sticky dock, above the keyboard after each focus route                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | ChatComposer ending under the keyboard, or moved a second time inside its dock, after any focus route                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | FR9      | TBD (Gap 1–11): a focus test per covered field, driving one keyboard change                                  | each covered field in the page, a Tall and a `hug` BottomSheet, ChatLayout's fixed and sticky dock, an app's fixed bar docked to the bottom edge with no `translate` of its own, and a fixed Toolbar docked there; focus by tap, Tab, and `focus()`; a field in scrolling content in the page and in a nested scroller; a field near its scroller's end; a field in a scroller inside a full-viewport fixed container                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | A focused page field or Core-host field left under the keyboard or less than 10 CSS px above it (a field with no scroller between it and a fixed container FR9 leaves to the app keeps the browser's own reveal and is not a failure; a field that a scroller holds inside such a container, left under the keyboard, is a failure), a field in an app's docked bar whose bar's bottom does not meet the keyboard's top, scroll range left at the scroller's end after the keyboard hides, a page pan or translate, a reveal later than the frame the keyboard is reported in, or a second offset inside a host that already applies the height                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
diff --git a/packages/core/src/Chat/useChatKeyboard.test.tsx b/packages/core/src/Chat/useChatKeyboard.test.tsx
index f25b08a8aa987..db59d53a4a42e 100644
--- a/packages/core/src/Chat/useChatKeyboard.test.tsx
+++ b/packages/core/src/Chat/useChatKeyboard.test.tsx
@@ -440,10 +440,20 @@ describe('ChatLayout in a page that scrolls the document', () => {
   // A first keyboard show where the dock stays covered, then a hide. The page
   // then knows that its browser does not pan to the dock.
   function learnCovered() {
+    focusComposer();
     report(window.innerHeight - 290);
     wait(800);
     report(window.innerHeight);
   }
+  // The keyboard comes up for the composer's text.
+  function focusComposer() {
+    const field = document.querySelector<HTMLElement>(
+      '[data-testid="layout"] textarea, [data-testid="layout"] [contenteditable="true"]',
+    );
+    act(() => {
+      field?.focus();
+    });
+  }
 
   function renderDocumentLayout(
     composer: ReactNode = (
@@ -452,7 +462,7 @@ describe('ChatLayout in a page that scrolls the document', () => {
       </div>
     ),
   ) {
-    return render(
+    const result = render(
       <ChatLayout
         data-testid="layout"
         scrollRef={{current: document.documentElement}}
@@ -460,6 +470,8 @@ describe('ChatLayout in a page that scrolls the document', () => {
         <p>Hello</p>
       </ChatLayout>,
     );
+    focusComposer();
+    return result;
   }
 
   it('lifts the fixed dock nothing in Safari on iOS, whose reveal pans the visual viewport to it and keeps the pan', () => {
@@ -737,7 +749,7 @@ describe('ChatLayout in a page that scrolls the document', () => {
     expect(isDockLeftCovered(window)).toBe(false);
   });
 
-  it('keeps the lift at a show that reached the cap when a touch came before the pan', () => {
+  it('follows the cover the pan leaves after the cap, so a later pan to the dock takes the lift away', () => {
     const {container} = renderDocumentLayout();
     report(window.innerHeight - 290);
     for (let i = 1; i <= 6; i += 1) {
@@ -748,17 +760,180 @@ describe('ChatLayout in a page that scrolls the document', () => {
     expect(layoutLift(dockOf(container))).toBe(290);
     drag();
     pan(290);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    expect(isDockLeftCovered(window)).toBe(false);
+  });
+
+  it('follows the cover the pan leaves once the reader scrolls after Firefox\u2019s own pan to the dock', () => {
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    wait(108);
+    pan(290);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    // A drag up the page: the browser unwinds its pan as the page scrolls.
+    act(() => {
+      document.dispatchEvent(touch('touchstart', [{x: 5, y: 300}]));
+    });
+    pan(200);
+    expect(layoutLift(dockOf(container))).toBe(90);
+    pan(100);
+    expect(layoutLift(dockOf(container))).toBe(190);
+    pan(0);
     expect(layoutLift(dockOf(container))).toBe(290);
+    act(() => {
+      document.dispatchEvent(touch('touchend', [{x: 5, y: 500}]));
+    });
+    pan(150);
+    expect(layoutLift(dockOf(container))).toBe(140);
+    expect(isDockLeftCovered(window)).toBe(false);
+  });
+
+  it('adds no lift while Safari keeps its pan through a scroll, and fills the cover where Safari unwinds it near the top', () => {
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 337);
+    wait(46);
+    pan(337);
+    drag();
+    act(() => {
+      viewport.dispatchEvent(new Event('scroll'));
+    });
+    expect(layoutLift(dockOf(container))).toBe(0);
+    pan(0);
+    expect(layoutLift(dockOf(container))).toBe(337);
+    pan(337);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    expect(isDockLeftCovered(window)).toBe(false);
+  });
+
+  it('holds the dock where the layout viewport follows the pan, as in Safari on iOS, through a slow scroll to the top of the page', () => {
+    // The initial containing block keeps its height; the layout viewport
+    // shrinks to the visual viewport while Safari pans.
+    const block = 714;
+    const inner = Object.getOwnPropertyDescriptor(window, 'innerHeight');
+    const setInnerHeight = (value: number) => {
+      Object.defineProperty(window, 'innerHeight', {configurable: true, value});
+    };
+    Object.defineProperty(document.documentElement, 'clientHeight', {
+      configurable: true,
+      get: () => block,
+    });
+    try {
+      setInnerHeight(block);
+      const {container} = renderDocumentLayout();
+      // Safari's reveal: a pan by the keyboard's cover, and the layout
+      // viewport shrinks to the visual viewport, so nothing is covered.
+      viewport.height = 377;
+      viewport.offsetTop = 337;
+      setInnerHeight(377);
+      act(() => {
+        viewport.dispatchEvent(new Event('resize'));
+      });
+      expect(layoutLift(dockOf(container))).toBe(0);
+      // A slow drag toward the top: Safari unwinds its pan, and the layout
+      // viewport grows by the same steps, up to the page's top.
+      for (let pan = 327; pan >= 7; pan -= 10) {
+        viewport.offsetTop = pan;
+        setInnerHeight(block - pan);
+        act(() => {
+          viewport.dispatchEvent(new Event('scroll'));
+        });
+        if (pan === 327) {
+          drag();
+        }
+        expect(layoutLift(dockOf(container))).toBe(0);
+      }
+      viewport.offsetTop = 0;
+      setInnerHeight(block);
+      act(() => {
+        viewport.dispatchEvent(new Event('scroll'));
+      });
+      expect(layoutLift(dockOf(container))).toBe(0);
+      wait(3000);
+      expect(layoutLift(dockOf(container))).toBe(0);
+      expect(isDockLeftCovered(window)).toBe(false);
+    } finally {
+      Reflect.deleteProperty(document.documentElement, 'clientHeight');
+      if (inner != null) {
+        Object.defineProperty(window, 'innerHeight', inner);
+      } else {
+        Reflect.deleteProperty(window, 'innerHeight');
+      }
+    }
+  });
+
+  it('holds the lift through a caret reveal while typing: a pan with no touch or wheel never starts following the cover', () => {
+    const {container} = renderDocumentLayout();
+    const field = screen.getByRole('textbox', {name: 'Message'});
+    report(window.innerHeight - 337);
+    wait(20);
+    // In the browser's own reveal: a caret pan, then the pan to the dock.
+    pan(120);
+    pan(337);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    // Typing raises key and input events, which are no touch or wheel.
+    act(() => {
+      field.dispatchEvent(
+        new KeyboardEvent('keydown', {key: 'a', bubbles: true}),
+      );
+      field.dispatchEvent(new Event('input', {bubbles: true}));
+    });
+    pan(317);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    wait(3000);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    expect(isDockLeftCovered(window)).toBe(false);
+  });
+
+  it('decides nothing at a show for a field outside the composer, and lifts the dock by the cover the pan leaves', () => {
+    const {container} = render(
+      <>
+        <input aria-label="Search" />
+        <ChatLayout
+          data-testid="layout"
+          scrollRef={{current: document.documentElement}}
+          composer={
+            <div data-testid="composer">
+              <textarea aria-label="Message" />
+            </div>
+          }>
+          <p>Hello</p>
+        </ChatLayout>
+      </>,
+    );
+    act(() => {
+      screen.getByRole('textbox', {name: 'Search'}).focus();
+    });
+    report(window.innerHeight - 337);
+    expect(layoutLift(dockOf(container))).toBe(337);
+    pan(100);
+    expect(layoutLift(dockOf(container))).toBe(237);
+    wait(3000);
+    expect(isDockLeftCovered(window)).toBe(false);
+    report(window.innerHeight);
+    pan(0);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    // The composer's own show is the browser's again: Safari pans to the dock.
+    focusComposer();
+    report(window.innerHeight - 337);
+    wait(46);
+    pan(337);
+    wait(3000);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    expect(isDockLeftCovered(window)).toBe(false);
+    expect(__focusTakeoverCallersForTest(document)).toBe(0);
   });
 
   it('leaves the composer\u2019s tap to the browser until a show finds the dock covered, then claims it', () => {
     renderDocumentLayout();
     const field = screen.getByRole('textbox', {name: 'Message'});
-    expect(tapText(field)).toBe(false);
     act(() => {
       field.blur();
     });
+    expect(tapText(field)).toBe(false);
     learnCovered();
+    act(() => {
+      field.blur();
+    });
     expect(tapText(field)).toBe(true);
   });
 
diff --git a/packages/core/src/Chat/useChatKeyboard.ts b/packages/core/src/Chat/useChatKeyboard.ts
index 462bbbb8c338a..1cd3536ce8e6a 100644
--- a/packages/core/src/Chat/useChatKeyboard.ts
+++ b/packages/core/src/Chat/useChatKeyboard.ts
@@ -29,10 +29,11 @@ import {createMotionEngine, type Animator} from '../motion/animator';
 import {
   claimTapFocus,
   findTextEntryControl,
+  followsDockDeficit,
   getDockRevealVersion,
   getKeyboardHeight,
+  getKeyboardPan,
   isDockLeftCovered,
-  isDockShowCovered,
   isTextEntryControl,
   refuseFocusReveal,
   subscribeDockReveal,
@@ -249,13 +250,18 @@ export function useChatKeyboard({
     // below the layout viewport's; a fixed dock rests at the viewport's.
     // While a keyboard is up the dock rises until it clears the keyboard's
     // cover; without one it rests where the layout puts it. Where the browser
-    // keeps the reveal, the dock rises only at a show the keyboard module
-    // finds it covered.
+    // keeps the reveal, the keyboard module decides the fixed dock's lift. It
+    // is the part of the cover that the browser's pan leaves.
     const leavesReveal = leavesRevealToBrowser(win, scrollRef.current);
     const liftFor = (inset: number) => {
-      if (inset <= 0 || (leavesReveal && !isDockShowCovered(win))) {
+      if (inset <= 0) {
         return 0;
       }
+      if (leavesReveal) {
+        return followsDockDeficit(win)
+          ? Math.max(0, inset - (getKeyboardPan(win) ?? 0))
+          : 0;
+      }
       // In layout px, as the root's rect is, under a pinch zoom too.
       const viewportBottom = layoutViewportHeight(win);
       const bottom = isSelfScrolling
@@ -352,10 +358,14 @@ export function useChatKeyboard({
         : undefined;
     // A height change the guide has no ride for, as for a resize or a
     // rotation, takes its lift at once. This listener comes after the guide's,
-    // so a ride claims the change first.
+    // so a ride claims the change first. Where the browser keeps the reveal,
+    // a pan changes the lift too.
     let reportedHeight = getKeyboardHeight(win);
     const unsubscribeHeight = subscribeKeyboardHeight(win, event => {
-      if (event.type === 'viewport' && event.height !== reportedHeight) {
+      if (
+        event.type === 'viewport' &&
+        (event.height !== reportedHeight || leavesReveal)
+      ) {
         reportedHeight = event.height;
         commit();
       }
@@ -444,9 +454,9 @@ export function useChatKeyboard({
   // A browser that reveals the composer itself pans the visual viewport after
   // the keyboard's report, while the composer still rides up. Chrome 124 on
   // Android pans by the keyboard's whole height. The keyboard module's
-  // reveal-pan watch puts the pan back, so the page does not move. In a page
-  // that scrolls the document with no layout guide, the watch also learns
-  // whether the browser reveals the fixed dock. If it does, it keeps that pan.
+  // reveal-pan watch puts the pan back, so the page does not move. With no
+  // layout guide, in a page that scrolls the document, the watch also decides
+  // at each show whether the browser pans to the dock. It keeps that pan.
   // Synchronizes the keyboard module's reports, under a finger only.
   useIsomorphicLayoutEffect(() => {
     const composer = composerRef.current;
diff --git a/packages/core/src/keyboard/README.md b/packages/core/src/keyboard/README.md
index 9a48e6aea9f53..e103494b1455c 100644
--- a/packages/core/src/keyboard/README.md
+++ b/packages/core/src/keyboard/README.md
@@ -72,16 +72,20 @@ that times motion with it. Everything here is internal to
   listener. `watchPans(win, owns)` (`keyboardTarget.ts`) runs that loop on
   each height the module reports: the keyboard targets and ChatLayout's
   composer watch with it. With `dock` (off by default), the watch also
-  decides once per keyboard show whether the browser pans the visual viewport
-  to a fixed dock in a page that scrolls the document. A pan to the dock
-  decides only its own show: no lift, and no pan is put back. A dock still
-  covered 0.7 s after the show's opening report rises. Only a pan restarts
-  that wait, up to 3 s; the height reports of the keyboard's slide do not.
-  With no touch or wheel in the wait, the page then learns that its browser
-  leaves the dock covered (`isDockLeftCovered(win)`), and every later show
-  lifts at once. A show with a touch or a wheel in the wait learns nothing. A
-  late pan to the dock after the lift, before any input, drops the lift and
-  forgets it. `getKeyboardPan(win)` gives the pan read with each report.
+  decides each keyboard show for a fixed dock in a page that scrolls the
+  document, while focus is in the dock. During the browser's own reveal, up to
+  a 0.7 s wait from the show's opening report, the dock does not move: a pan
+  to it decides only that show, and no pan is put back. Only a pan restarts the
+  wait, up to 3 s; the height reports of the keyboard's slide do not. A dock
+  still covered when a clean wait ends teaches the page that its browser leaves
+  it covered (`isDockLeftCovered(win)`), and every later show works as on main.
+  Otherwise, and after any touch or wheel once the reveal is over, the dock
+  follows the part of the cover the pan leaves (`followsDockDeficit(win)`). A
+  show for a field outside the dock follows it from the start. Where the layout
+  viewport's height follows the pan, as in Safari on iOS, the dock holds for the
+  rest of the show: the height and the pan then add up to the keyboard's cover
+  of the initial containing block, which each report carries.
+  `getKeyboardPan(win)` gives the pan read with each report.
 - **Keyboard targets (`keyboardTarget.ts`):** a target keeps the focused field
   inside it above the keyboard, and registers so a field inside moves nothing
   itself (`registerKeyboardTarget`, `isInsideKeyboardTarget`).
diff --git a/packages/core/src/keyboard/keyboardHeight.test.ts b/packages/core/src/keyboard/keyboardHeight.test.ts
index 551d37ecb89ba..8b31f3a441a37 100644
--- a/packages/core/src/keyboard/keyboardHeight.test.ts
+++ b/packages/core/src/keyboard/keyboardHeight.test.ts
@@ -949,7 +949,7 @@ describe('the browser\u2019s own reveal pan (FR4)', () => {
     expect(runs[0]).toEqual([false, false, true, false, false]);
   });
 
-  it('with the dock option, shares one wheel subscription among its watches', () => {
+  it('with the dock option, listens for wheels through the shared input stream', () => {
     const add = vi.spyOn(window, 'addEventListener');
     const remove = vi.spyOn(window, 'removeEventListener');
     const first = watchRevealPan(window, {owns: () => true, dock: true});
diff --git a/packages/core/src/keyboard/keyboardHeight.ts b/packages/core/src/keyboard/keyboardHeight.ts
index 3371d9f4c2d43..f0123c4b3de53 100644
--- a/packages/core/src/keyboard/keyboardHeight.ts
+++ b/packages/core/src/keyboard/keyboardHeight.ts
@@ -71,13 +71,36 @@ export function isKeyboardMeasurable(win: Window): boolean {
  * `isKeyboardMeasurable` is false.
  */
 export function measureKeyboardHeight(win: Window): number {
+  return measureReport(win).height;
+}
+
+interface KeyboardMeasure {
+  height: number;
+  pan: number | null;
+  cover: number | null;
+}
+
+// One read of the visual viewport: the keyboard's height, the viewport's pan
+// and how far the keyboard covers the initial containing block. The last two
+// are null under a pinch zoom, whose pan is the reader's. Safari on iOS can
+// shrink the layout viewport to the visual viewport while it pans, but the
+// initial containing block keeps its height.
+function measureReport(win: Window): KeyboardMeasure {
   const viewport = win.visualViewport;
   if (viewport == null || !isKeyboardMeasurable(win)) {
-    return 0;
+    return {height: 0, pan: null, cover: null};
   }
-  const height =
-    layoutViewportHeight(win) - viewport.height * (viewport.scale ?? 1);
-  return height > KEYBOARD_EPSILON ? Math.round(height * 100) / 100 : 0;
+  const scale = viewport.scale ?? 1;
+  const visualHeight = viewport.height;
+  const height = layoutViewportHeight(win) - visualHeight * scale;
+  const isUnzoomed = scale === 1;
+  return {
+    height: height > KEYBOARD_EPSILON ? Math.round(height * 100) / 100 : 0,
+    pan: isUnzoomed ? viewport.offsetTop : null,
+    cover: isUnzoomed
+      ? Math.max(0, win.document.documentElement.clientHeight - visualHeight)
+      : null,
+  };
 }
 
 /** A report from the keyboard module, in the order the window raised them. */
@@ -103,6 +126,8 @@ interface KeyboardStore {
   height: number;
   /** The visual viewport's pan at the last report (getKeyboardPan). */
   pan: number | null;
+  /** The keyboard's cover of the initial containing block at that report. */
+  cover: number | null;
   listeners: Set<(event: KeyboardHeightEvent) => void>;
   /** The subscribers that asked for focus moves too (the layout guide). */
   focusListeners: Set<(event: KeyboardHeightEvent) => void>;
@@ -118,6 +143,7 @@ function storeOf(win: Window): KeyboardStore {
     store = {
       height: 0,
       pan: null,
+      cover: null,
       listeners: new Set(),
       focusListeners: new Set(),
       detach: null,
@@ -150,23 +176,28 @@ function isHideStep(win: Window, shown: number, height: number): boolean {
 
 function attach(win: Window, store: KeyboardStore): () => void {
   const viewport = win.visualViewport;
-  store.height = measureKeyboardHeight(win);
-  store.pan = measurePan(win);
+  const first = measureReport(win);
+  store.height = first.height;
+  store.pan = first.pan;
+  store.cover = first.cover;
   // Set while a step of a hide waits. The store keeps the height it reported,
   // so every reader lays out once, when the keyboard comes to rest.
   let stepTimer: ReturnType<typeof setTimeout> | null = null;
   let stepHeight = 0;
   let stepLimit = 0;
-  const deliver = (height: number, timeStamp: number) => {
+  const deliver = (measure: KeyboardMeasure, timeStamp: number) => {
+    const {height} = measure;
     store.height = height;
-    store.pan = measurePan(win);
+    store.pan = measure.pan;
+    store.cover = measure.cover;
     const report: KeyboardHeightEvent = {type: 'viewport', height, timeStamp};
     for (const listener of [...store.listeners]) {
       listener(report);
     }
   };
   const onViewport = (event: Event) => {
-    const height = measureKeyboardHeight(win);
+    const measure = measureReport(win);
+    const {height} = measure;
     if (isHideStep(win, store.height, height)) {
       // A pan reports the same step again, and leaves the wait as it is.
       if (
@@ -186,7 +217,7 @@ function attach(win: Window, store: KeyboardStore): () => void {
       stepTimer = setTimeout(
         () => {
           stepTimer = null;
-          deliver(measureKeyboardHeight(win), win.performance.now());
+          deliver(measureReport(win), win.performance.now());
         },
         Math.min(HIDE_STEP_WAIT_MS, stepLimit - now),
       );
@@ -196,7 +227,7 @@ function attach(win: Window, store: KeyboardStore): () => void {
       clearTimeout(stepTimer);
       stepTimer = null;
     }
-    deliver(height, event.timeStamp);
+    deliver(measure, event.timeStamp);
   };
   viewport?.addEventListener('resize', onViewport);
   viewport?.addEventListener('scroll', onViewport);
@@ -555,42 +586,6 @@ function watchTouchStarts(doc: Document, onTouchStart: () => void): () => void {
   };
 }
 
-// One shared wheel subscription per document serves every dock watch in it,
-// as the touch subscription above serves the reveal-pan watches.
-const wheelWatches = new WeakMap<
-  Document,
-  {stop: () => void; watches: Set<() => void>}
->();
-
-function watchWheels(doc: Document, onWheel: () => void): () => void {
-  let shared = wheelWatches.get(doc);
-  if (shared == null) {
-    const view = doc.defaultView;
-    if (view == null) {
-      return () => {};
-    }
-    const watches = new Set<() => void>();
-    const stop = subscribeInput(view, 'wheel', () => {
-      for (const watch of [...watches]) {
-        watch();
-      }
-    });
-    shared = {stop, watches};
-    wheelWatches.set(doc, shared);
-  }
-  shared.watches.add(onWheel);
-  return () => {
-    const current = wheelWatches.get(doc);
-    if (current == null || !current.watches.delete(onWheel)) {
-      return;
-    }
-    if (current.watches.size === 0) {
-      current.stop();
-      wheelWatches.delete(doc);
-    }
-  };
-}
-
 // How long a dock's keyboard show waits for the browser's own pan to the
 // dock, from the show's opening report. Only a pan restarts the wait: the
 // height reports of the keyboard's slide do not. The cap ends a wait that pans
@@ -602,10 +597,11 @@ const DOCK_REVEAL_CAP_MS = 3000;
 // The windows whose browser left a fixed dock covered at a keyboard show with
 // no touch or wheel in the wait.
 const docksLeftCovered = new WeakSet<Window>();
-// The windows whose current show found the dock covered without learning it.
-// That is at the wait's cap, or after a touch or a wheel in the wait. Such a
-// show lifts the dock but teaches nothing.
-const coveredShows = new WeakSet<Window>();
+// The windows whose current show lifts the dock by the part of the cover the
+// visual viewport's pan leaves, and teaches nothing. That is a show for a
+// field outside the dock. It is also a show with a touch or a wheel once the
+// browser's own reveal is over.
+const deficitShows = new WeakSet<Window>();
 const dockRevealListeners = new Set<() => void>();
 let dockRevealVersion = 0;
 
@@ -637,12 +633,15 @@ export function isDockLeftCovered(win: Window): boolean {
   return docksLeftCovered.has(win);
 }
 
-/** Whether the fixed dock in `win` stays covered at this keyboard show. */
-export function isDockShowCovered(win: Window): boolean {
-  return docksLeftCovered.has(win) || coveredShows.has(win);
+/**
+ * Whether the fixed dock in `win` rises at this keyboard show by the part of
+ * the cover the visual viewport's pan leaves (getKeyboardPan).
+ */
+export function followsDockDeficit(win: Window): boolean {
+  return deficitShows.has(win);
 }
 
-/** Calls `listener` when isDockLeftCovered or isDockShowCovered changes. */
+/** Calls `listener` when isDockLeftCovered or followsDockDeficit changes. */
 export function subscribeDockReveal(listener: () => void): () => void {
   dockRevealListeners.add(listener);
   return () => {
@@ -663,22 +662,33 @@ export function getDockRevealVersion(): number {
  */
 export function __resetDockRevealForTest(win: Window): void {
   const known = docksLeftCovered.delete(win);
-  if (coveredShows.delete(win) || known) {
+  if (deficitShows.delete(win) || known) {
     notifyDockReveal();
   }
 }
 
-// The dock's watch: one decision per keyboard show. A pan to the dock decides
-// that show alone: no lift. A dock still covered when the wait ends rises.
-// With no touch or wheel in the wait, the page learns that its browser leaves
-// the dock covered. Only the show that learned it, before any input, still
-// meets a slow browser's pan: the lift then goes, and the page forgets it.
-function watchDock(win: Window): {
+// The dock's watch: one decision per keyboard show for the dock's field. A
+// pan to the dock decides that show alone: no lift. A dock still covered when
+// the wait ends rises. With no touch or wheel in the wait, the page learns that
+// its browser leaves the dock covered. Only the show that learned it, before
+// any input, still meets a slow browser's pan: the lift then goes, and the page
+// forgets it. After a touch or a wheel, once the browser's reveal is over, the
+// dock follows the part of the cover that the pan leaves. So a reader's scroll
+// that moves the pan keeps the dock on the keyboard.
+function watchDock(
+  win: Window,
+  owns: (focused: HTMLElement) => boolean,
+): {
   report: (height: number) => boolean;
   input: () => void;
   stop: () => void;
 } {
-  let show: 'none' | 'watching' | 'revealed' | 'covered' = 'none';
+  let show: 'none' | 'other' | 'watching' | 'revealed' | 'covered' | 'deficit' =
+    'none';
+  // Set once the show finds the layout viewport's height following the pan,
+  // as in Safari on iOS. The dock then holds for the rest of the show: a lift
+  // there makes the browser reveal the focused field again.
+  let layoutFollowsPan = false;
   let lastPan = getKeyboardPan(win);
   let coveredPan = 0;
   let isClassifying = false;
@@ -696,32 +706,50 @@ function watchDock(win: Window): {
       capTimer = null;
     }
   };
+  const ownsFocus = () => {
+    const focused = win.document.activeElement;
+    return focused instanceof HTMLElement && owns(focused);
+  };
   // With no lift, the dock rests at or above the visual viewport's bottom.
   const isRevealed = (pan: number | null, height: number): pan is number =>
     pan != null && pan >= height - 1;
   // A pan the browser made before any input of the show.
   const isRevealPan = (pan: number | null, height: number): pan is number =>
     !inputSinceShow && isRevealed(pan, height);
-  const cover = (learn: boolean) => {
+  const followDeficit = () => {
     clearTimers();
-    show = 'covered';
-    coveredPan = getKeyboardPan(win) ?? 0;
-    if (learn) {
-      isClassifying = true;
-      learnDockLeftCovered(win, true);
-    } else {
-      coveredShows.add(win);
+    show = 'deficit';
+    if (!layoutFollowsPan && !deficitShows.has(win)) {
+      deficitShows.add(win);
       notifyDockReveal();
     }
   };
-  // Where the dock rests when the wait ends decides the show. Only a clean
-  // wait that ends on its own teaches the page.
+  // The layout viewport shrinks as the pan grows: the height and the pan add
+  // up to the cover of the initial containing block.
+  const seesLayoutFollowPan = (height: number, pan: number | null) => {
+    const cover = stores.get(win)?.cover ?? null;
+    return (
+      pan != null &&
+      pan > 0.5 &&
+      cover != null &&
+      height < cover - 1 &&
+      Math.abs(height + pan - cover) <= 1.5
+    );
+  };
+  // The wait's end decides the show. Only a clean wait that ends on its own
+  // teaches the page.
   const settle = (atCap: boolean) => {
-    if (isRevealed(getKeyboardPan(win), getKeyboardHeight(win))) {
-      clearTimers();
+    clearTimers();
+    const revealed = isRevealed(getKeyboardPan(win), getKeyboardHeight(win));
+    if (inputSinceShow || atCap) {
+      followDeficit();
+    } else if (revealed) {
       show = 'revealed';
     } else {
-      cover(!atCap && !inputSinceShow);
+      show = 'covered';
+      coveredPan = getKeyboardPan(win) ?? 0;
+      isClassifying = true;
+      learnDockLeftCovered(win, true);
     }
   };
   const restartSettle = () => {
@@ -737,8 +765,11 @@ function watchDock(win: Window): {
   };
   const markInput = () => {
     inputSinceShow = true;
+    if (show === 'revealed') {
+      followDeficit();
+    }
   };
-  const stopWheels = watchWheels(win.document, markInput);
+  const stopWheels = subscribeInput(win, 'wheel', markInput);
   const report = (height: number): boolean => {
     const pan = getKeyboardPan(win);
     const panned =
@@ -750,17 +781,31 @@ function watchDock(win: Window): {
       clearTimers();
       show = 'none';
       isClassifying = false;
-      if (coveredShows.delete(win)) {
+      layoutFollowsPan = false;
+      if (deficitShows.delete(win)) {
         notifyDockReveal();
       }
       return !docksLeftCovered.has(win);
     }
+    if (!layoutFollowsPan && seesLayoutFollowPan(height, pan)) {
+      layoutFollowsPan = true;
+      if (deficitShows.delete(win)) {
+        notifyDockReveal();
+      }
+    }
     if (show === 'none') {
       inputSinceShow = false;
       if (docksLeftCovered.has(win)) {
         show = 'covered';
         return false;
       }
+      // A field outside the dock: the browser reveals that field, and the
+      // dock follows what is left of the cover.
+      if (!ownsFocus()) {
+        followDeficit();
+        show = 'other';
+        return true;
+      }
       if (isRevealed(pan, height)) {
         show = 'revealed';
         return true;
@@ -784,20 +829,15 @@ function watchDock(win: Window): {
       }
       return true;
     }
-    if (show === 'covered' && (isClassifying || coveredShows.has(win))) {
+    if (show === 'covered' && isClassifying) {
       if (isRevealPan(pan, height) && pan > coveredPan + 0.5) {
         show = 'revealed';
         isClassifying = false;
-        const wasCoveredShow = coveredShows.delete(win);
-        if (docksLeftCovered.has(win)) {
-          learnDockLeftCovered(win, false);
-        } else if (wasCoveredShow) {
-          notifyDockReveal();
-        }
+        learnDockLeftCovered(win, false);
       }
       return true;
     }
-    return show === 'revealed';
+    return show !== 'covered';
   };
   return {
     report,
@@ -833,7 +873,7 @@ export function watchRevealPan(
   {owns, onTouch, dock = false}: WatchRevealPanOptions,
 ): RevealPanWatch {
   const doc = win.document;
-  const dockWatch = dock ? watchDock(win) : null;
+  const dockWatch = dock ? watchDock(win, owns) : null;
   let atReport: {x: number; y: number; top: number; scale: number} | null =
     null;
   let touchedSinceReport = false;

From 05167c1aa74a38fdc060fa67f673ee6768f7c4d7 Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 8 Nov 2026 15:49:04 -0800
Subject: [PATCH 11/16] fix(ChatLayout): follow the pan on the dock's translate

While the dock follows the cover a pan leaves, each keyboard report
now moves only the dock's translate, from the keyboard module's
numbers, with no layout read or write. The layout takes the lift
once, when the reader's scroll comes to rest: at a lifted finger or
at the scroll's end, through the shared input stream.

A composer show under a pinch zoom, whose pan is the reader's, now
teaches nothing: its dock follows the cover instead.
---
 docs/specs/AST-099-mobile-keyboard/spec.md    |  23 ++--
 .../cli/assets/docs/browser-support.doc.mjs   |   2 +-
 .../core/src/Chat/useChatKeyboard.test.tsx    | 109 +++++++++++++++---
 packages/core/src/Chat/useChatKeyboard.ts     |  67 +++++++++--
 packages/core/src/keyboard/README.md          |   1 +
 packages/core/src/keyboard/keyboardHeight.ts  |  11 +-
 6 files changed, 176 insertions(+), 37 deletions(-)

diff --git a/docs/specs/AST-099-mobile-keyboard/spec.md b/docs/specs/AST-099-mobile-keyboard/spec.md
index ec2c2487607a1..3711b72a829b6 100644
--- a/docs/specs/AST-099-mobile-keyboard/spec.md
+++ b/docs/specs/AST-099-mobile-keyboard/spec.md
@@ -110,12 +110,13 @@ app to turn on.
   While the browser's own reveal runs, the dock does not move (Gap 16). Then the
   dock rises by the part of the keyboard's cover that the visual viewport's pan
   leaves. A pan to the dock leaves none, so the dock rises nothing. After a
-  touch or a wheel, the dock follows that part as a scroll moves the pan. Where
-  the layout viewport's height follows the pan instead, as in Safari on iOS, the
-  dock does not move for the rest of that show (Gap 17). Once a show finds the
-  dock covered, the composer is a keyboard-aware surface there, as elsewhere.
-  FR9's
-  docked ride is the one exception: Core moves an app's docked bar as FR9 sets
+  touch or a wheel, the dock follows that part on its translate as a scroll
+  moves the pan. The layout takes the lift once, when the scroll comes to rest.
+  Where the layout viewport's height follows the pan instead, as in Safari on
+  iOS, the dock does not move for the rest of that show (Gap 17). Once a show
+  finds the dock covered, the composer is a keyboard-aware surface there, as
+  elsewhere. FR9's docked ride is the one exception: Core moves an app's
+  docked bar as FR9 sets
   out. How the value reaches styles is `architecture:react-component-runtime`
   INV11. Riding the keyboard's motion layers on top of that layout, so layout
   never depends on it; FR8 requires it where it applies. When surfaces ride it,
@@ -405,11 +406,11 @@ No covered field meets FR9 on `main`. Each gap below is open.
   covered keeps the composer covered until the wait ends. With a slow-device
   profile, that is about 0.75 s (731 to 755 ms). Only a pan of the visual
   viewport restarts the wait, and the wait ends at 3 s at most. Every later show
-  lifts the dock at once. A show with a touch or a wheel in the wait teaches
-  nothing. When its wait ends, its dock follows the part of the cover that the
-  pan leaves. On the iOS Simulator, Safari's pan arrived 0 to 400 ms after the
-  keyboard's report. A short cover once, at Firefox's first covered show, is
-  better than a lift and then a drop in a slow Safari.
+  lifts the dock at once. A show with a touch or a wheel in the wait, or under a
+  pinch zoom, teaches nothing. When its wait ends, its dock follows the part of
+  the cover that the pan leaves. On the iOS Simulator, Safari's pan arrived 0 to
+  400 ms after the keyboard's report. A short cover once, at Firefox's first
+  covered show, is better than a lift and then a drop in a slow Safari.
 - **Gap 17 — Safari on iOS on a slow scroll toward the top with the keyboard
   up.** In a page that scrolls the document, Safari on iOS unwinds its own pan
   as the reader scrolls toward the page's top with the keyboard up. Its layout
diff --git a/packages/cli/assets/docs/browser-support.doc.mjs b/packages/cli/assets/docs/browser-support.doc.mjs
index 60569e35d4139..adb37b74434fb 100644
--- a/packages/cli/assets/docs/browser-support.doc.mjs
+++ b/packages/cli/assets/docs/browser-support.doc.mjs
@@ -148,7 +148,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "On a phone, the components that respond to the on-screen keyboard, a fully expanded `height='tall'` BottomSheet and ChatLayout's composer, measure it the same way: the layout viewport's height minus the visual viewport's height times its scale. Where the visual viewport shrinks for the keyboard, as in Safari on iOS in the browser and as a home-screen app, in Firefox for Android and in Chrome on Android, they keep the focused field and the surface around it above the keyboard and leave the page where it was. If Firefox for Android pans to the field, they put the page back within a couple of frames. One exception applies when ChatLayout's scrollRef names the document. Safari on iOS then reveals the composer itself and keeps its focus. In another browser without the VirtualKeyboard API, the first keyboard show that leaves the composer covered waits a short time before the composer rises.",
+          text: "On a phone, the components that respond to the on-screen keyboard, a fully expanded `height='tall'` BottomSheet and ChatLayout's composer, measure it the same way: the layout viewport's height minus the visual viewport's height times its scale. Where the visual viewport shrinks for the keyboard, as in Safari on iOS in the browser and as a home-screen app, in Firefox for Android and in Chrome on Android, they keep the focused field and the surface around it above the keyboard and leave the page where it was. If Firefox for Android pans to the field, they put the page back within a couple of frames. One exception applies when ChatLayout's scrollRef names the document. Safari on iOS then reveals the composer itself and keeps its focus. In another browser without the VirtualKeyboard API, each show before that keeps the browser\u2019s pan to the composer. The first keyboard show that leaves the composer covered waits a short time before the composer rises.",
         },
         {
           type: 'prose',
diff --git a/packages/core/src/Chat/useChatKeyboard.test.tsx b/packages/core/src/Chat/useChatKeyboard.test.tsx
index db59d53a4a42e..80f34e17d8421 100644
--- a/packages/core/src/Chat/useChatKeyboard.test.tsx
+++ b/packages/core/src/Chat/useChatKeyboard.test.tsx
@@ -423,6 +423,12 @@ describe('ChatLayout in a page that scrolls the document', () => {
       document.dispatchEvent(touch('touchend', [{x: 5, y: 50}]));
     });
   }
+  // The reader's scroll comes to rest.
+  function rest() {
+    act(() => {
+      document.dispatchEvent(new Event('scrollend'));
+    });
+  }
   function wheel() {
     act(() => {
       document.dispatchEvent(new Event('wheel'));
@@ -591,7 +597,13 @@ describe('ChatLayout in a page that scrolls the document', () => {
       wait(500);
       pan(i % 2 === 1 ? 10 : 0);
     }
-    expect(layoutLift(dockOf(container))).toBeGreaterThanOrEqual(290);
+    // The cap takes the cover the last pan left; the next pan moves only the
+    // dock's translate until the scroll rests.
+    expect(layoutLift(dockOf(container))).toBe(280);
+    expect(dockOf(container).style.translate).toBe('0px -10px');
+    rest();
+    expect(layoutLift(dockOf(container))).toBe(290);
+    expect(dockOf(container).style.translate).toBe('');
     expect(isDockLeftCovered(window)).toBe(false);
     report(window.innerHeight);
     expect(layoutLift(dockOf(container))).toBe(0);
@@ -756,15 +768,18 @@ describe('ChatLayout in a page that scrolls the document', () => {
       wait(500);
       pan(i % 2 === 1 ? 10 : 0);
     }
-    report(window.innerHeight - 290);
+    rest();
     expect(layoutLift(dockOf(container))).toBe(290);
     drag();
     pan(290);
+    expect(dockOf(container).style.translate).toBe('0px 290px');
+    rest();
     expect(layoutLift(dockOf(container))).toBe(0);
+    expect(dockOf(container).style.translate).toBe('');
     expect(isDockLeftCovered(window)).toBe(false);
   });
 
-  it('follows the cover the pan leaves once the reader scrolls after Firefox\u2019s own pan to the dock', () => {
+  it('follows the cover the pan leaves on the dock\u2019s translate once the reader scrolls after Firefox\u2019s own pan, and lays it out once at rest', () => {
     const {container} = renderDocumentLayout();
     report(window.innerHeight - 290);
     wait(108);
@@ -774,17 +789,56 @@ describe('ChatLayout in a page that scrolls the document', () => {
     act(() => {
       document.dispatchEvent(touch('touchstart', [{x: 5, y: 300}]));
     });
-    pan(200);
-    expect(layoutLift(dockOf(container))).toBe(90);
-    pan(100);
-    expect(layoutLift(dockOf(container))).toBe(190);
-    pan(0);
-    expect(layoutLift(dockOf(container))).toBe(290);
-    act(() => {
-      document.dispatchEvent(touch('touchend', [{x: 5, y: 500}]));
+    const root = document.documentElement;
+    const scrollTop = Object.getOwnPropertyDescriptor(
+      Element.prototype,
+      'scrollTop',
+    )!;
+    let scrollReads = 0;
+    Object.defineProperty(root, 'scrollTop', {
+      configurable: true,
+      get(this: Element) {
+        scrollReads += 1;
+        return scrollTop.get!.call(this) as number;
+      },
+      set(this: Element, value: number) {
+        scrollTop.set!.call(this, value);
+      },
     });
-    pan(150);
-    expect(layoutLift(dockOf(container))).toBe(140);
+    try {
+      const lifts: number[] = [];
+      const rooms: number[] = [];
+      for (const [panTo, translate] of [
+        [200, '0px -90px'],
+        [100, '0px -190px'],
+        [0, '0px -290px'],
+      ] as const) {
+        pan(panTo);
+        expect(dockOf(container).style.translate).toBe(translate);
+        lifts.push(layoutLift(dockOf(container)));
+        rooms.push(keyboardRoom(messagesOf()));
+      }
+      // While the reader scrolls, nothing is laid out and nothing is read.
+      expect(lifts).toEqual([0, 0, 0]);
+      expect(rooms).toEqual([0, 0, 0]);
+      expect(scrollReads).toBe(0);
+      act(() => {
+        document.dispatchEvent(touch('touchend', [{x: 5, y: 500}]));
+      });
+      expect(layoutLift(dockOf(container))).toBe(290);
+      expect(keyboardRoom(messagesOf())).toBe(290);
+      expect(dockOf(container).style.translate).toBe('');
+      // A fling's momentum follows on the translate too, and its end lays it
+      // out.
+      pan(150);
+      expect(dockOf(container).style.translate).toBe('0px 150px');
+      expect(layoutLift(dockOf(container))).toBe(290);
+      rest();
+      expect(layoutLift(dockOf(container))).toBe(140);
+      expect(dockOf(container).style.translate).toBe('');
+    } finally {
+      Reflect.deleteProperty(root, 'scrollTop');
+    }
     expect(isDockLeftCovered(window)).toBe(false);
   });
 
@@ -799,9 +853,13 @@ describe('ChatLayout in a page that scrolls the document', () => {
     });
     expect(layoutLift(dockOf(container))).toBe(0);
     pan(0);
+    expect(dockOf(container).style.translate).toBe('0px -337px');
+    rest();
     expect(layoutLift(dockOf(container))).toBe(337);
     pan(337);
+    rest();
     expect(layoutLift(dockOf(container))).toBe(0);
+    expect(dockOf(container).style.translate).toBe('');
     expect(isDockLeftCovered(window)).toBe(false);
   });
 
@@ -861,6 +919,29 @@ describe('ChatLayout in a page that scrolls the document', () => {
     }
   });
 
+  it('learns nothing from a composer show under a pinch zoom, whose pan is the reader\u2019s, and lifts the dock by the cover', () => {
+    const {container} = renderDocumentLayout();
+    viewport.scale = 2;
+    // At a 2x zoom, a 290 px cover of the layout viewport.
+    report((window.innerHeight - 290) / 2);
+    wait(700);
+    expect(isDockLeftCovered(window)).toBe(false);
+    expect(layoutLift(dockOf(container))).toBe(290);
+    report(window.innerHeight / 2);
+    viewport.scale = 1;
+    report(window.innerHeight);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    // The next show at normal zoom is the browser's again: Safari pans to the
+    // dock, and the dock rises nothing.
+    report(window.innerHeight - 337);
+    wait(46);
+    pan(337);
+    wait(3000);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    expect(isDockLeftCovered(window)).toBe(false);
+    expect(__focusTakeoverCallersForTest(document)).toBe(0);
+  });
+
   it('holds the lift through a caret reveal while typing: a pan with no touch or wheel never starts following the cover', () => {
     const {container} = renderDocumentLayout();
     const field = screen.getByRole('textbox', {name: 'Message'});
@@ -906,6 +987,8 @@ describe('ChatLayout in a page that scrolls the document', () => {
     report(window.innerHeight - 337);
     expect(layoutLift(dockOf(container))).toBe(337);
     pan(100);
+    expect(dockOf(container).style.translate).toBe('0px 100px');
+    rest();
     expect(layoutLift(dockOf(container))).toBe(237);
     wait(3000);
     expect(isDockLeftCovered(window)).toBe(false);
diff --git a/packages/core/src/Chat/useChatKeyboard.ts b/packages/core/src/Chat/useChatKeyboard.ts
index 1cd3536ce8e6a..11b19e9a9c623 100644
--- a/packages/core/src/Chat/useChatKeyboard.ts
+++ b/packages/core/src/Chat/useChatKeyboard.ts
@@ -4,9 +4,9 @@
 
 /**
  * @file useChatKeyboard.ts
- * @input React refs, the keyboard module's height, focus routes and layout
+ * @input React refs, the keyboard module's reports, focus routes and layout
  *   guide, the stream scroll's lock, the motion engine, the touch query and
- *   layout viewport height
+ *   layout viewport height. Also the input stream's touch ends and scroll ends
  * @output Exports useChatKeyboard: the lift for ChatLayout's dock and message
  *   area, and the refs for its dock, message area and composer region. It
  *   also tells whether a focus call in the composer skips the browser's reveal
@@ -51,6 +51,7 @@ import {
 import type {KeyboardTransition} from '../keyboard/keyboardModel';
 import {rideKeyboard} from '../keyboard/rideKeyboard';
 import {layoutViewportHeight} from '../utils/layoutViewport';
+import {subscribeInput} from '../utils/inputStream';
 import {
   useInteractionModalityTrackingFor,
   type InteractionModality,
@@ -229,6 +230,9 @@ export function useChatKeyboard({
   // (null: the transcript did not ride), until the layout takes them over.
   const dockTargetRef = useRef<number | null>(null);
   const messagesTargetRef = useRef<number | null>(null);
+  // Set while the dock's translate carries a change of the pan's cover that
+  // the layout has not taken yet.
+  const panPendingRef = useRef(false);
   // Whether the transcript followed its newest message, and where it was
   // scrolled, just before the layout's last change.
   const atEndRef = useRef(false);
@@ -282,13 +286,39 @@ export function useChatKeyboard({
         return;
       }
       const next = liftFor(getKeyboardHeight(win));
-      if (Math.abs(next - liftRef.current) < 0.5) {
+      const moves = Math.abs(next - liftRef.current) >= 0.5;
+      // The layout takes over the translate a followed pan left.
+      if (panPendingRef.current) {
+        panPendingRef.current = false;
+        dockTargetRef.current = moves ? liftRef.current - next : null;
+        if (!moves) {
+          dock.animator.set({y: 0});
+        }
+      }
+      if (!moves) {
         return;
       }
       atEndRef.current = isAtEnd();
       scrollBeforeRef.current = scrollRef.current?.scrollTop ?? 0;
       liftStore.set(next);
     };
+    // While the dock follows the cover a pan leaves, a report moves only the
+    // dock's translate, from the keyboard module's numbers. The layout takes
+    // the lift once, when the reader's scroll comes to rest.
+    const followPan = (height: number) => {
+      const target = liftRef.current - liftFor(height);
+      if (Math.abs(target) < 0.5) {
+        if (panPendingRef.current) {
+          panPendingRef.current = false;
+          dockTargetRef.current = null;
+          dock.animator.set({y: 0});
+        }
+        return;
+      }
+      panPendingRef.current = true;
+      dockTargetRef.current = target;
+      dock.animator.set({y: target});
+    };
 
     // The ride plays the curve the guide publishes with each transition: the
     // keyboard's own motion. These are values, not motion roles, since the
@@ -362,17 +392,38 @@ export function useChatKeyboard({
     // a pan changes the lift too.
     let reportedHeight = getKeyboardHeight(win);
     const unsubscribeHeight = subscribeKeyboardHeight(win, event => {
-      if (
-        event.type === 'viewport' &&
-        (event.height !== reportedHeight || leavesReveal)
-      ) {
-        reportedHeight = event.height;
+      if (event.type !== 'viewport') {
+        return;
+      }
+      const changed = event.height !== reportedHeight;
+      reportedHeight = event.height;
+      if (leavesReveal && event.height > 0 && followsDockDeficit(win)) {
+        followPan(event.height);
+      } else if (changed || leavesReveal) {
         commit();
       }
     });
+    // A scroll that comes to rest, or a lifted finger, hands a followed pan's
+    // lift to the layout.
+    const onRest = (event: Event) => {
+      const touches = (event as Partial<TouchEvent>).touches;
+      if (panPendingRef.current && !(touches != null && touches.length > 0)) {
+        commit();
+      }
+    };
+    const stopRest = leavesReveal
+      ? [
+          subscribeInput(win, 'touchend', onRest),
+          subscribeInput(win, 'touchcancel', onRest),
+          subscribeInput(win, 'scrollend', onRest),
+        ]
+      : [];
     // Mounted under a keyboard that is already up: take its place at once.
     commit();
     return () => {
+      for (const stop of stopRest) {
+        stop();
+      }
       unsubscribeHeight();
       unsubscribe?.();
       ridingRef.current = false;
diff --git a/packages/core/src/keyboard/README.md b/packages/core/src/keyboard/README.md
index e103494b1455c..018c11cb4a063 100644
--- a/packages/core/src/keyboard/README.md
+++ b/packages/core/src/keyboard/README.md
@@ -79,6 +79,7 @@ that times motion with it. Everything here is internal to
   wait, up to 3 s; the height reports of the keyboard's slide do not. A dock
   still covered when a clean wait ends teaches the page that its browser leaves
   it covered (`isDockLeftCovered(win)`), and every later show works as on main.
+  A show under a pinch zoom, whose pan is the reader's, learns nothing.
   Otherwise, and after any touch or wheel once the reveal is over, the dock
   follows the part of the cover the pan leaves (`followsDockDeficit(win)`). A
   show for a field outside the dock follows it from the start. Where the layout
diff --git a/packages/core/src/keyboard/keyboardHeight.ts b/packages/core/src/keyboard/keyboardHeight.ts
index f0123c4b3de53..5e0e398555015 100644
--- a/packages/core/src/keyboard/keyboardHeight.ts
+++ b/packages/core/src/keyboard/keyboardHeight.ts
@@ -84,7 +84,8 @@ interface KeyboardMeasure {
 // and how far the keyboard covers the initial containing block. The last two
 // are null under a pinch zoom, whose pan is the reader's. Safari on iOS can
 // shrink the layout viewport to the visual viewport while it pans, but the
-// initial containing block keeps its height.
+// initial containing block keeps its height. layoutViewportHeight reads the
+// root's client height in the same batch, so that read adds no layout.
 function measureReport(win: Window): KeyboardMeasure {
   const viewport = win.visualViewport;
   if (viewport == null || !isKeyboardMeasurable(win)) {
@@ -737,11 +738,13 @@ function watchDock(
     );
   };
   // The wait's end decides the show. Only a clean wait that ends on its own
-  // teaches the page.
+  // teaches the page. Under a pinch zoom the pan is the reader's, so that show
+  // teaches nothing either.
   const settle = (atCap: boolean) => {
     clearTimers();
-    const revealed = isRevealed(getKeyboardPan(win), getKeyboardHeight(win));
-    if (inputSinceShow || atCap) {
+    const pan = getKeyboardPan(win);
+    const revealed = isRevealed(pan, getKeyboardHeight(win));
+    if (inputSinceShow || atCap || pan == null) {
       followDeficit();
     } else if (revealed) {
       show = 'revealed';

From 7262c34aa585d4674b3e8624efd0e8a9bd3ad496 Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 8 Nov 2026 15:57:23 -0800
Subject: [PATCH 12/16] fix(ChatLayout): a pan's fling that moves no document
 rests too

A fling that pans only the visual viewport raises no document scroll
end, so its followed lift waited for the next lifted finger. The
keyboard module now passes on the visual viewport's own scroll end
(subscribeViewportRest, one shared listener per window), and a
report that finds the pan unchanged also counts as rest.
---
 .../core/src/Chat/useChatKeyboard.test.tsx    | 45 ++++++++++++++++
 packages/core/src/Chat/useChatKeyboard.ts     | 37 +++++++++----
 packages/core/src/keyboard/README.md          |  4 +-
 .../core/src/keyboard/keyboardHeight.test.ts  | 20 +++++++
 packages/core/src/keyboard/keyboardHeight.ts  | 53 ++++++++++++++++++-
 5 files changed, 147 insertions(+), 12 deletions(-)

diff --git a/packages/core/src/Chat/useChatKeyboard.test.tsx b/packages/core/src/Chat/useChatKeyboard.test.tsx
index 80f34e17d8421..f60b2f0d03e1a 100644
--- a/packages/core/src/Chat/useChatKeyboard.test.tsx
+++ b/packages/core/src/Chat/useChatKeyboard.test.tsx
@@ -919,6 +919,51 @@ describe('ChatLayout in a page that scrolls the document', () => {
     }
   });
 
+  it('lays out a followed pan once when a fling that pans only the visual viewport comes to rest, with no touch end', () => {
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    wait(108);
+    pan(290);
+    act(() => {
+      document.dispatchEvent(touch('touchstart', [{x: 5, y: 300}]));
+    });
+    pan(200);
+    pan(100);
+    expect(dockOf(container).style.translate).toBe('0px -190px');
+    expect(layoutLift(dockOf(container))).toBe(0);
+    // The fling pans the visual viewport alone: no document scroll end, and
+    // the finger is still down.
+    act(() => {
+      viewport.dispatchEvent(new Event('scrollend'));
+    });
+    expect(layoutLift(dockOf(container))).toBe(190);
+    expect(dockOf(container).style.translate).toBe('');
+    // A later report with the pan unchanged lays out nothing more.
+    act(() => {
+      viewport.dispatchEvent(new Event('resize'));
+    });
+    expect(layoutLift(dockOf(container))).toBe(190);
+  });
+
+  it('lays out a followed pan at the first report after the pan stops moving', () => {
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    wait(108);
+    pan(290);
+    act(() => {
+      document.dispatchEvent(touch('touchstart', [{x: 5, y: 300}]));
+    });
+    pan(150);
+    expect(layoutLift(dockOf(container))).toBe(0);
+    expect(dockOf(container).style.translate).toBe('0px -140px');
+    // A report with the same pan and height, as a toolbar's resize raises.
+    act(() => {
+      viewport.dispatchEvent(new Event('resize'));
+    });
+    expect(layoutLift(dockOf(container))).toBe(140);
+    expect(dockOf(container).style.translate).toBe('');
+  });
+
   it('learns nothing from a composer show under a pinch zoom, whose pan is the reader\u2019s, and lifts the dock by the cover', () => {
     const {container} = renderDocumentLayout();
     viewport.scale = 2;
diff --git a/packages/core/src/Chat/useChatKeyboard.ts b/packages/core/src/Chat/useChatKeyboard.ts
index 11b19e9a9c623..e955e0158b788 100644
--- a/packages/core/src/Chat/useChatKeyboard.ts
+++ b/packages/core/src/Chat/useChatKeyboard.ts
@@ -38,6 +38,7 @@ import {
   refuseFocusReveal,
   subscribeDockReveal,
   subscribeKeyboardHeight,
+  subscribeViewportRest,
 } from '../keyboard/keyboardHeight';
 import {
   getKeyboardLayoutGuide,
@@ -391,31 +392,49 @@ export function useChatKeyboard({
     // so a ride claims the change first. Where the browser keeps the reveal,
     // a pan changes the lift too.
     let reportedHeight = getKeyboardHeight(win);
+    let reportedPan = getKeyboardPan(win);
     const unsubscribeHeight = subscribeKeyboardHeight(win, event => {
       if (event.type !== 'viewport') {
         return;
       }
       const changed = event.height !== reportedHeight;
+      const pan = getKeyboardPan(win);
+      const panned =
+        pan == null || reportedPan == null
+          ? pan !== reportedPan
+          : Math.abs(pan - reportedPan) >= 0.5;
       reportedHeight = event.height;
+      reportedPan = pan;
       if (leavesReveal && event.height > 0 && followsDockDeficit(win)) {
-        followPan(event.height);
+        // A report after the pan stopped moving: the pan is at rest.
+        if (!changed && !panned && panPendingRef.current) {
+          commit();
+        } else {
+          followPan(event.height);
+        }
       } else if (changed || leavesReveal) {
         commit();
       }
     });
-    // A scroll that comes to rest, or a lifted finger, hands a followed pan's
-    // lift to the layout.
-    const onRest = (event: Event) => {
-      const touches = (event as Partial<TouchEvent>).touches;
-      if (panPendingRef.current && !(touches != null && touches.length > 0)) {
+    // A scroll that comes to rest, the visual viewport's included, or a lifted
+    // finger hands a followed pan's lift to the layout.
+    const rest = () => {
+      if (panPendingRef.current) {
         commit();
       }
     };
+    const onTouchEnd = (event: Event) => {
+      const touches = (event as Partial<TouchEvent>).touches;
+      if (!(touches != null && touches.length > 0)) {
+        rest();
+      }
+    };
     const stopRest = leavesReveal
       ? [
-          subscribeInput(win, 'touchend', onRest),
-          subscribeInput(win, 'touchcancel', onRest),
-          subscribeInput(win, 'scrollend', onRest),
+          subscribeInput(win, 'touchend', onTouchEnd),
+          subscribeInput(win, 'touchcancel', onTouchEnd),
+          subscribeInput(win, 'scrollend', rest),
+          subscribeViewportRest(win, rest),
         ]
       : [];
     // Mounted under a keyboard that is already up: take its place at once.
diff --git a/packages/core/src/keyboard/README.md b/packages/core/src/keyboard/README.md
index 018c11cb4a063..9295882898b3e 100644
--- a/packages/core/src/keyboard/README.md
+++ b/packages/core/src/keyboard/README.md
@@ -86,7 +86,9 @@ that times motion with it. Everything here is internal to
   viewport's height follows the pan, as in Safari on iOS, the dock holds for the
   rest of the show: the height and the pan then add up to the keyboard's cover
   of the initial containing block, which each report carries.
-  `getKeyboardPan(win)` gives the pan read with each report.
+  `getKeyboardPan(win)` gives the pan read with each report, and
+  `subscribeViewportRest(win, listener)` hears the visual viewport's scroll end
+  through one shared listener per window.
 - **Keyboard targets (`keyboardTarget.ts`):** a target keeps the focused field
   inside it above the keyboard, and registers so a field inside moves nothing
   itself (`registerKeyboardTarget`, `isInsideKeyboardTarget`).
diff --git a/packages/core/src/keyboard/keyboardHeight.test.ts b/packages/core/src/keyboard/keyboardHeight.test.ts
index 8b31f3a441a37..06b772758c583 100644
--- a/packages/core/src/keyboard/keyboardHeight.test.ts
+++ b/packages/core/src/keyboard/keyboardHeight.test.ts
@@ -34,6 +34,7 @@ import {
   measureKeyboardHeight,
   refuseFocusReveal,
   subscribeKeyboardHeight,
+  subscribeViewportRest,
   watchRevealPan,
   type KeyboardHeightEvent,
 } from './keyboardHeight';
@@ -968,6 +969,25 @@ describe('the browser\u2019s own reveal pan (FR4)', () => {
   });
 });
 
+describe('the visual viewport\u2019s rest', () => {
+  it('shares one scroll-end listener on the visual viewport among its callers', () => {
+    const add = vi.spyOn(viewport, 'addEventListener');
+    const remove = vi.spyOn(viewport, 'removeEventListener');
+    const heard: string[] = [];
+    const stopFirst = subscribeViewportRest(window, () => heard.push('first'));
+    const stopSecond = subscribeViewportRest(window, () =>
+      heard.push('second'),
+    );
+    expect(add.mock.calls.map(([type]) => type)).toEqual(['scrollend']);
+    viewport.dispatchEvent(new Event('scrollend'));
+    expect(heard).toEqual(['first', 'second']);
+    stopFirst();
+    expect(remove).not.toHaveBeenCalled();
+    stopSecond();
+    expect(remove.mock.calls.map(([type]) => type)).toEqual(['scrollend']);
+  });
+});
+
 describe('the visual viewport\u2019s pan with each report', () => {
   it('is read with the report\u2019s height, and is none under a pinch zoom', () => {
     const stop = subscribeKeyboardHeight(window, () => {});
diff --git a/packages/core/src/keyboard/keyboardHeight.ts b/packages/core/src/keyboard/keyboardHeight.ts
index 5e0e398555015..45b3fb3b52e88 100644
--- a/packages/core/src/keyboard/keyboardHeight.ts
+++ b/packages/core/src/keyboard/keyboardHeight.ts
@@ -9,8 +9,9 @@
  * @output The on-screen keyboard module: measureKeyboardHeight,
  *   isKeyboardMeasurable, hasVirtualKeyboard, subscribeKeyboardHeight,
  *   getKeyboardHeight, getKeyboardPan, isTextEntryControl,
- *   findTextEntryControl, refuseFocusReveal and watchRevealPan. It also keeps
- *   whether a window's browser leaves a fixed dock covered (isDockLeftCovered)
+ *   findTextEntryControl, refuseFocusReveal, watchRevealPan and
+ *   subscribeViewportRest. It also keeps whether a window's browser leaves a
+ *   fixed dock covered (isDockLeftCovered)
  * @position Core's one source for the on-screen keyboard. It is internal to
  *   core and never exported from the package.
  *
@@ -513,6 +514,54 @@ export function __focusTakeoverCallersForTest(doc: Document): number {
   return focusTakeovers.get(doc)?.callers.size ?? 0;
 }
 
+// One shared listener per window hears the visual viewport's scroll end, for
+// every caller. The first caller adds it, and the last removes it.
+const viewportRests = new WeakMap<
+  Window,
+  {stop: () => void; listeners: Set<() => void>}
+>();
+
+/**
+ * Calls `listener` when a scroll of `win`'s visual viewport comes to rest,
+ * such as the end of a pan's fling. A pan that moves no document scroller
+ * raises no document scroll end. Returns the unsubscribe function.
+ */
+export function subscribeViewportRest(
+  win: Window,
+  listener: () => void,
+): () => void {
+  let shared = viewportRests.get(win);
+  if (shared == null) {
+    const viewport = win.visualViewport;
+    if (viewport == null) {
+      return () => {};
+    }
+    const listeners = new Set<() => void>();
+    const onRest = () => {
+      for (const each of [...listeners]) {
+        each();
+      }
+    };
+    viewport.addEventListener('scrollend', onRest);
+    shared = {
+      stop: () => viewport.removeEventListener('scrollend', onRest),
+      listeners,
+    };
+    viewportRests.set(win, shared);
+  }
+  shared.listeners.add(listener);
+  return () => {
+    const current = viewportRests.get(win);
+    if (current == null || !current.listeners.delete(listener)) {
+      return;
+    }
+    if (current.listeners.size === 0) {
+      current.stop();
+      viewportRests.delete(win);
+    }
+  };
+}
+
 /** The caller's rules for watchRevealPan. */
 export interface WatchRevealPanOptions {
   /** Whether the focused field is the caller's to keep in view. */

From 729784099d46cbc0076a5b7c968ec945e42cea82 Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 8 Nov 2026 16:05:24 -0800
Subject: [PATCH 13/16] fix(ChatLayout): a slow drag never counts as rest

A report whose pan moved less than half a pixel counted as rest, so a
slow drag laid out the lift every few reports. Now only a report that
finds the pan exactly where it was, with no finger down, counts as
rest: the exact repeat that ends a fling's momentum. The hook keeps
the count of fingers down across its effect runs.
---
 .../core/src/Chat/useChatKeyboard.test.tsx    | 41 +++++++++++++++++--
 packages/core/src/Chat/useChatKeyboard.ts     | 26 ++++++++----
 2 files changed, 56 insertions(+), 11 deletions(-)

diff --git a/packages/core/src/Chat/useChatKeyboard.test.tsx b/packages/core/src/Chat/useChatKeyboard.test.tsx
index f60b2f0d03e1a..353c1937bbde5 100644
--- a/packages/core/src/Chat/useChatKeyboard.test.tsx
+++ b/packages/core/src/Chat/useChatKeyboard.test.tsx
@@ -945,7 +945,7 @@ describe('ChatLayout in a page that scrolls the document', () => {
     expect(layoutLift(dockOf(container))).toBe(190);
   });
 
-  it('lays out a followed pan at the first report after the pan stops moving', () => {
+  it('lays out a followed pan at the first report after the pan stops moving, once no finger is down', () => {
     const {container} = renderDocumentLayout();
     report(window.innerHeight - 290);
     wait(108);
@@ -953,9 +953,15 @@ describe('ChatLayout in a page that scrolls the document', () => {
     act(() => {
       document.dispatchEvent(touch('touchstart', [{x: 5, y: 300}]));
     });
+    pan(200);
+    act(() => {
+      document.dispatchEvent(touch('touchend', [{x: 5, y: 500}]));
+    });
+    expect(layoutLift(dockOf(container))).toBe(90);
+    // The fling's momentum moves the pan on, then stops.
     pan(150);
-    expect(layoutLift(dockOf(container))).toBe(0);
-    expect(dockOf(container).style.translate).toBe('0px -140px');
+    expect(layoutLift(dockOf(container))).toBe(90);
+    expect(dockOf(container).style.translate).toBe('0px -50px');
     // A report with the same pan and height, as a toolbar's resize raises.
     act(() => {
       viewport.dispatchEvent(new Event('resize'));
@@ -964,6 +970,35 @@ describe('ChatLayout in a page that scrolls the document', () => {
     expect(dockOf(container).style.translate).toBe('');
   });
 
+  it('lays out nothing during a slow drag, whatever the size of each step, until the finger lifts', () => {
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    wait(108);
+    pan(290);
+    act(() => {
+      document.dispatchEvent(touch('touchstart', [{x: 5, y: 300}]));
+    });
+    const lifts: number[] = [];
+    for (let step = 1; step <= 10; step += 1) {
+      pan(290 - step * 0.3);
+      // A report with the pan where it was, while the finger is still down.
+      act(() => {
+        viewport.dispatchEvent(new Event('resize'));
+      });
+      lifts.push(layoutLift(dockOf(container)));
+    }
+    expect(lifts.every(lift => lift === 0)).toBe(true);
+    const translateY = Number(
+      /^0px (-?[\d.]+)px$/.exec(dockOf(container).style.translate)?.[1],
+    );
+    expect(translateY).toBeCloseTo(-3, 5);
+    act(() => {
+      document.dispatchEvent(touch('touchend', [{x: 5, y: 303}]));
+    });
+    expect(layoutLift(dockOf(container))).toBeCloseTo(3, 5);
+    expect(dockOf(container).style.translate).toBe('');
+  });
+
   it('learns nothing from a composer show under a pinch zoom, whose pan is the reader\u2019s, and lifts the dock by the cover', () => {
     const {container} = renderDocumentLayout();
     viewport.scale = 2;
diff --git a/packages/core/src/Chat/useChatKeyboard.ts b/packages/core/src/Chat/useChatKeyboard.ts
index e955e0158b788..45d20ba440eeb 100644
--- a/packages/core/src/Chat/useChatKeyboard.ts
+++ b/packages/core/src/Chat/useChatKeyboard.ts
@@ -234,6 +234,9 @@ export function useChatKeyboard({
   // Set while the dock's translate carries a change of the pan's cover that
   // the layout has not taken yet.
   const panPendingRef = useRef(false);
+  // Fingers on the screen: while one is down, the reader still moves the pan,
+  // however slowly.
+  const fingersRef = useRef(0);
   // Whether the transcript followed its newest message, and where it was
   // scrolled, just before the layout's last change.
   const atEndRef = useRef(false);
@@ -399,15 +402,18 @@ export function useChatKeyboard({
       }
       const changed = event.height !== reportedHeight;
       const pan = getKeyboardPan(win);
-      const panned =
-        pan == null || reportedPan == null
-          ? pan !== reportedPan
-          : Math.abs(pan - reportedPan) >= 0.5;
       reportedHeight = event.height;
+      const isPanStill = pan === reportedPan;
       reportedPan = pan;
       if (leavesReveal && event.height > 0 && followsDockDeficit(win)) {
-        // A report after the pan stopped moving: the pan is at rest.
-        if (!changed && !panned && panPendingRef.current) {
+        // A report that finds the pan where it was, with no finger down: the
+        // pan is at rest.
+        if (
+          !changed &&
+          isPanStill &&
+          fingersRef.current === 0 &&
+          panPendingRef.current
+        ) {
           commit();
         } else {
           followPan(event.height);
@@ -423,14 +429,18 @@ export function useChatKeyboard({
         commit();
       }
     };
+    const onTouchStart = (event: Event) => {
+      fingersRef.current = (event as Partial<TouchEvent>).touches?.length ?? 1;
+    };
     const onTouchEnd = (event: Event) => {
-      const touches = (event as Partial<TouchEvent>).touches;
-      if (!(touches != null && touches.length > 0)) {
+      fingersRef.current = (event as Partial<TouchEvent>).touches?.length ?? 0;
+      if (fingersRef.current === 0) {
         rest();
       }
     };
     const stopRest = leavesReveal
       ? [
+          subscribeInput(win, 'touchstart', onTouchStart),
           subscribeInput(win, 'touchend', onTouchEnd),
           subscribeInput(win, 'touchcancel', onTouchEnd),
           subscribeInput(win, 'scrollend', rest),

From ab435926f24160d231d30f6a3bf4ad57e89a1074 Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 8 Nov 2026 16:41:32 -0800
Subject: [PATCH 14/16] fix(ChatLayout): the Safari hold is tested, and a hide
 forgets touches

The Safari slow-scroll case now asserts that the dock's translate
stays empty, so removing the hold fails it. A keyboard hide resets
the hook's finger count, so a lift the effect never heard cannot
keep a later fling from resting. The comment says why the input
stream's down presses cannot serve. FR3 says the layout takes the
lift when the last finger lifts, and again when a fling rests.
---
 docs/specs/AST-099-mobile-keyboard/spec.md    | 12 ++++----
 .../core/src/Chat/useChatKeyboard.test.tsx    | 30 ++++++++++++++++++-
 packages/core/src/Chat/useChatKeyboard.ts     | 11 +++++--
 3 files changed, 44 insertions(+), 9 deletions(-)

diff --git a/docs/specs/AST-099-mobile-keyboard/spec.md b/docs/specs/AST-099-mobile-keyboard/spec.md
index 3711b72a829b6..cff051082aafe 100644
--- a/docs/specs/AST-099-mobile-keyboard/spec.md
+++ b/docs/specs/AST-099-mobile-keyboard/spec.md
@@ -111,12 +111,12 @@ app to turn on.
   dock rises by the part of the keyboard's cover that the visual viewport's pan
   leaves. A pan to the dock leaves none, so the dock rises nothing. After a
   touch or a wheel, the dock follows that part on its translate as a scroll
-  moves the pan. The layout takes the lift once, when the scroll comes to rest.
-  Where the layout viewport's height follows the pan instead, as in Safari on
-  iOS, the dock does not move for the rest of that show (Gap 17). Once a show
-  finds the dock covered, the composer is a keyboard-aware surface there, as
-  elsewhere. FR9's docked ride is the one exception: Core moves an app's
-  docked bar as FR9 sets
+  moves the pan. The layout takes the lift when the last finger lifts, and again
+  when a fling comes to rest. Where the layout viewport's height follows the pan
+  instead, as in Safari on iOS, the dock does not move for the rest of that show
+  (Gap 17). Once a show finds the dock covered, the composer is a keyboard-aware
+  surface there, as elsewhere. FR9's docked ride is the one exception: Core
+  moves an app's docked bar as FR9 sets
   out. How the value reaches styles is `architecture:react-component-runtime`
   INV11. Riding the keyboard's motion layers on top of that layout, so layout
   never depends on it; FR8 requires it where it applies. When surfaces ride it,
diff --git a/packages/core/src/Chat/useChatKeyboard.test.tsx b/packages/core/src/Chat/useChatKeyboard.test.tsx
index 353c1937bbde5..9ab7c4f4987ed 100644
--- a/packages/core/src/Chat/useChatKeyboard.test.tsx
+++ b/packages/core/src/Chat/useChatKeyboard.test.tsx
@@ -779,7 +779,7 @@ describe('ChatLayout in a page that scrolls the document', () => {
     expect(isDockLeftCovered(window)).toBe(false);
   });
 
-  it('follows the cover the pan leaves on the dock\u2019s translate once the reader scrolls after Firefox\u2019s own pan, and lays it out once at rest', () => {
+  it('follows the cover the pan leaves on the dock\u2019s translate once the reader scrolls after Firefox\u2019s own pan, and lays it out when the finger lifts and when the fling rests', () => {
     const {container} = renderDocumentLayout();
     report(window.innerHeight - 290);
     wait(108);
@@ -899,6 +899,7 @@ describe('ChatLayout in a page that scrolls the document', () => {
           drag();
         }
         expect(layoutLift(dockOf(container))).toBe(0);
+        expect(dockOf(container).style.translate).toBe('');
       }
       viewport.offsetTop = 0;
       setInnerHeight(block);
@@ -908,6 +909,7 @@ describe('ChatLayout in a page that scrolls the document', () => {
       expect(layoutLift(dockOf(container))).toBe(0);
       wait(3000);
       expect(layoutLift(dockOf(container))).toBe(0);
+      expect(dockOf(container).style.translate).toBe('');
       expect(isDockLeftCovered(window)).toBe(false);
     } finally {
       Reflect.deleteProperty(document.documentElement, 'clientHeight');
@@ -970,6 +972,32 @@ describe('ChatLayout in a page that scrolls the document', () => {
     expect(dockOf(container).style.translate).toBe('');
   });
 
+  it('forgets a finger whose lift it never heard once the keyboard hides, so a later fling still comes to rest', () => {
+    const {container} = renderDocumentLayout();
+    report(window.innerHeight - 290);
+    wait(108);
+    pan(290);
+    // A finger goes down, and its lift is never heard.
+    act(() => {
+      document.dispatchEvent(touch('touchstart', [{x: 5, y: 300}]));
+    });
+    report(window.innerHeight);
+    pan(0);
+    // The next show: Firefox pans, then a wheel scrolls the page.
+    report(window.innerHeight - 290);
+    wait(108);
+    pan(290);
+    wheel();
+    pan(150);
+    expect(dockOf(container).style.translate).toBe('0px -140px');
+    // The pan's momentum ends in an exact repeat, with no finger down.
+    act(() => {
+      viewport.dispatchEvent(new Event('resize'));
+    });
+    expect(layoutLift(dockOf(container))).toBe(140);
+    expect(dockOf(container).style.translate).toBe('');
+  });
+
   it('lays out nothing during a slow drag, whatever the size of each step, until the finger lifts', () => {
     const {container} = renderDocumentLayout();
     report(window.innerHeight - 290);
diff --git a/packages/core/src/Chat/useChatKeyboard.ts b/packages/core/src/Chat/useChatKeyboard.ts
index 45d20ba440eeb..887522d6da1fb 100644
--- a/packages/core/src/Chat/useChatKeyboard.ts
+++ b/packages/core/src/Chat/useChatKeyboard.ts
@@ -235,7 +235,9 @@ export function useChatKeyboard({
   // the layout has not taken yet.
   const panPendingRef = useRef(false);
   // Fingers on the screen: while one is down, the reader still moves the pan,
-  // however slowly.
+  // however slowly. The input stream's getDownPresses cannot serve. The
+  // browser cancels a finger's pointer once its touch starts to scroll, and
+  // the stream drops the press then.
   const fingersRef = useRef(0);
   // Whether the transcript followed its newest message, and where it was
   // scrolled, just before the layout's last change.
@@ -308,7 +310,8 @@ export function useChatKeyboard({
     };
     // While the dock follows the cover a pan leaves, a report moves only the
     // dock's translate, from the keyboard module's numbers. The layout takes
-    // the lift once, when the reader's scroll comes to rest.
+    // the lift when the last finger lifts, and again when a fling comes to
+    // rest.
     const followPan = (height: number) => {
       const target = liftRef.current - liftFor(height);
       if (Math.abs(target) < 0.5) {
@@ -403,6 +406,10 @@ export function useChatKeyboard({
       const changed = event.height !== reportedHeight;
       const pan = getKeyboardPan(win);
       reportedHeight = event.height;
+      // A keyboard hide ends any touch this effect may not have heard end.
+      if (event.height <= 0) {
+        fingersRef.current = 0;
+      }
       const isPanStill = pan === reportedPan;
       reportedPan = pan;
       if (leavesReveal && event.height > 0 && followsDockDeficit(win)) {

From a64d445a4223cf0193c60cbf1f7f6daf336bf093 Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 8 Nov 2026 16:46:25 -0800
Subject: [PATCH 15/16] docs(AST-099): FR3 states the dock's follow and a
 fling's two layouts

FR3 now says plainly that the dock follows the pan on its compositor
translate, with no layout work at each change of the visual viewport.
It also says the layout takes the lift when the last finger lifts,
and again when a fling comes to rest. The hook's comment matches.
---
 docs/specs/AST-099-mobile-keyboard/spec.md | 16 +++++++++-------
 packages/core/src/Chat/useChatKeyboard.ts  |  4 ++--
 2 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/docs/specs/AST-099-mobile-keyboard/spec.md b/docs/specs/AST-099-mobile-keyboard/spec.md
index cff051082aafe..2a63c8fcda74b 100644
--- a/docs/specs/AST-099-mobile-keyboard/spec.md
+++ b/docs/specs/AST-099-mobile-keyboard/spec.md
@@ -110,13 +110,15 @@ app to turn on.
   While the browser's own reveal runs, the dock does not move (Gap 16). Then the
   dock rises by the part of the keyboard's cover that the visual viewport's pan
   leaves. A pan to the dock leaves none, so the dock rises nothing. After a
-  touch or a wheel, the dock follows that part on its translate as a scroll
-  moves the pan. The layout takes the lift when the last finger lifts, and again
-  when a fling comes to rest. Where the layout viewport's height follows the pan
-  instead, as in Safari on iOS, the dock does not move for the rest of that show
-  (Gap 17). Once a show finds the dock covered, the composer is a keyboard-aware
-  surface there, as elsewhere. FR9's docked ride is the one exception: Core
-  moves an app's docked bar as FR9 sets
+  touch or a wheel, the dock follows that part as a scroll moves the pan. It
+  follows on its compositor translate, with no layout work at each change of the
+  visual viewport. The layout takes the lift when the last finger lifts. After a
+  fling, the layout takes it again when the fling comes to rest. Where the
+  layout viewport's height follows the pan instead, as in Safari on iOS, the
+  dock does not move for the rest of that show (Gap 17). Once a show finds the
+  dock covered, the composer is a keyboard-aware surface there, as elsewhere.
+  FR9's docked ride is the one exception: Core moves an app's docked bar as FR9
+  sets
   out. How the value reaches styles is `architecture:react-component-runtime`
   INV11. Riding the keyboard's motion layers on top of that layout, so layout
   never depends on it; FR8 requires it where it applies. When surfaces ride it,
diff --git a/packages/core/src/Chat/useChatKeyboard.ts b/packages/core/src/Chat/useChatKeyboard.ts
index 887522d6da1fb..b1273b93f2def 100644
--- a/packages/core/src/Chat/useChatKeyboard.ts
+++ b/packages/core/src/Chat/useChatKeyboard.ts
@@ -310,8 +310,8 @@ export function useChatKeyboard({
     };
     // While the dock follows the cover a pan leaves, a report moves only the
     // dock's translate, from the keyboard module's numbers. The layout takes
-    // the lift when the last finger lifts, and again when a fling comes to
-    // rest.
+    // the lift when the last finger lifts. After a fling, it takes it again
+    // when the fling comes to rest.
     const followPan = (height: number) => {
       const target = liftRef.current - liftFor(height);
       if (Math.abs(target) < 0.5) {

From 8e190c33e06545599b04fa0cd23a2d8dc8fe4bbb Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 8 Nov 2026 18:44:34 -0800
Subject: [PATCH 16/16] fix(ChatLayout): a learned cover survives a later pan
 to the dock

In the show that learned the browser leaves the dock covered, a pan
to the dock before any input dropped the lift and forgot what the
page learned, so the next show waited again. In Firefox for Android
under Remove animations a reveal can land after the lift. Now that
pan goes back, as at every later show, and the page keeps the cover.
The dock watch puts it back itself: the module's own put-back
measures from the opening report, before the lift moved the layout.
---
 .../core/src/Chat/useChatKeyboard.test.tsx    | 122 ++++++++++++++----
 packages/core/src/keyboard/README.md          |   4 +-
 packages/core/src/keyboard/keyboardHeight.ts  |  81 ++++++------
 3 files changed, 141 insertions(+), 66 deletions(-)

diff --git a/packages/core/src/Chat/useChatKeyboard.test.tsx b/packages/core/src/Chat/useChatKeyboard.test.tsx
index 9ab7c4f4987ed..69624f514777b 100644
--- a/packages/core/src/Chat/useChatKeyboard.test.tsx
+++ b/packages/core/src/Chat/useChatKeyboard.test.tsx
@@ -480,6 +480,47 @@ describe('ChatLayout in a page that scrolls the document', () => {
     return result;
   }
 
+  // Android's Remove animations: the keyboard shows in one step, and reduced
+  // motion applies.
+  function reduceMotion() {
+    vi.stubGlobal('matchMedia', (query: string) => ({
+      matches:
+        query === '(pointer: coarse)' ||
+        query === '(prefers-reduced-motion: reduce)',
+      media: query,
+      addEventListener: () => {},
+      removeEventListener: () => {},
+    }));
+  }
+
+  it('keeps a page\u2019s learned cover through a pan to the dock after the lift, under Remove animations: the pan goes back, and the next show lifts at once', () => {
+    reduceMotion();
+    const scrollIntoView = vi.fn();
+    Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', {
+      configurable: true,
+      value: scrollIntoView,
+    });
+    try {
+      const {container} = renderDocumentLayout();
+      report(window.innerHeight - 290);
+      wait(700);
+      expect(isDockLeftCovered(window)).toBe(true);
+      expect(layoutLift(dockOf(container))).toBe(290);
+      // The browser pans to the composer after the lift, before any input.
+      wait(50);
+      pan(290);
+      expect(scrollIntoView).toHaveBeenCalledTimes(1);
+      expect(layoutLift(dockOf(container))).toBe(290);
+      expect(isDockLeftCovered(window)).toBe(true);
+      report(window.innerHeight);
+      pan(0);
+      report(window.innerHeight - 290);
+      expect(layoutLift(dockOf(container))).toBe(290);
+    } finally {
+      Reflect.deleteProperty(HTMLElement.prototype, 'scrollIntoView');
+    }
+  });
+
   it('lifts the fixed dock nothing in Safari on iOS, whose reveal pans the visual viewport to it and keeps the pan', () => {
     const {container} = renderDocumentLayout();
     // Safari's reveal: the keyboard's report comes with a pan by its height.
@@ -634,34 +675,67 @@ describe('ChatLayout in a page that scrolls the document', () => {
     expect(isDockLeftCovered(window)).toBe(false);
   });
 
-  it('drops the lift once for a slow browser whose pan to the dock comes after the wait, with no input since the show opened', () => {
-    const {container} = renderDocumentLayout();
-    report(window.innerHeight - 337);
-    wait(800);
-    expect(layoutLift(dockOf(container))).toBe(337);
-    pan(337);
-    expect(layoutLift(dockOf(container))).toBe(0);
-    expect(isDockLeftCovered(window)).toBe(false);
-    expect(__focusTakeoverCallersForTest(document)).toBe(0);
+  it('puts back a pan to the dock that comes after the show learned the cover, with no input since the show opened, and keeps the lift', () => {
+    const scrollIntoView = vi.fn();
+    Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', {
+      configurable: true,
+      value: scrollIntoView,
+    });
+    try {
+      const {container} = renderDocumentLayout();
+      report(window.innerHeight - 337);
+      wait(800);
+      expect(layoutLift(dockOf(container))).toBe(337);
+      pan(337);
+      expect(scrollIntoView).toHaveBeenCalledTimes(1);
+      expect(layoutLift(dockOf(container))).toBe(337);
+      expect(isDockLeftCovered(window)).toBe(true);
+      expect(__focusTakeoverCallersForTest(document)).toBe(1);
+      // A pan smaller than the cover is no reveal: nothing goes back.
+      pan(40);
+      expect(scrollIntoView).toHaveBeenCalledTimes(1);
+    } finally {
+      Reflect.deleteProperty(HTMLElement.prototype, 'scrollIntoView');
+    }
   });
 
-  it('keeps the lift for a reveal-sized pan after a touch, as a reader\u2019s fling to the end', () => {
-    const {container} = renderDocumentLayout();
-    report(window.innerHeight - 290);
-    wait(800);
-    drag();
-    pan(290);
-    expect(layoutLift(dockOf(container))).toBe(290);
-    expect(isDockLeftCovered(window)).toBe(true);
+  it('keeps the lift, and leaves the pan, for a reveal-sized pan after a touch, as a reader\u2019s fling to the end', () => {
+    const scrollIntoView = vi.fn();
+    Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', {
+      configurable: true,
+      value: scrollIntoView,
+    });
+    try {
+      const {container} = renderDocumentLayout();
+      report(window.innerHeight - 290);
+      wait(800);
+      drag();
+      pan(290);
+      expect(layoutLift(dockOf(container))).toBe(290);
+      expect(isDockLeftCovered(window)).toBe(true);
+      expect(scrollIntoView).not.toHaveBeenCalled();
+    } finally {
+      Reflect.deleteProperty(HTMLElement.prototype, 'scrollIntoView');
+    }
   });
 
-  it('keeps the lift for a reveal-sized pan after a wheel', () => {
-    const {container} = renderDocumentLayout();
-    report(window.innerHeight - 290);
-    wait(800);
-    wheel();
-    pan(290);
-    expect(layoutLift(dockOf(container))).toBe(290);
+  it('keeps the lift, and leaves the pan, for a reveal-sized pan after a wheel', () => {
+    const scrollIntoView = vi.fn();
+    Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', {
+      configurable: true,
+      value: scrollIntoView,
+    });
+    try {
+      const {container} = renderDocumentLayout();
+      report(window.innerHeight - 290);
+      wait(800);
+      wheel();
+      pan(290);
+      expect(layoutLift(dockOf(container))).toBe(290);
+      expect(scrollIntoView).not.toHaveBeenCalled();
+    } finally {
+      Reflect.deleteProperty(HTMLElement.prototype, 'scrollIntoView');
+    }
   });
 
   it('keeps the input gate closed through a report during a drag, such as a toolbar\u2019s resize', () => {
diff --git a/packages/core/src/keyboard/README.md b/packages/core/src/keyboard/README.md
index 9295882898b3e..af0da68bf4c6e 100644
--- a/packages/core/src/keyboard/README.md
+++ b/packages/core/src/keyboard/README.md
@@ -79,7 +79,9 @@ that times motion with it. Everything here is internal to
   wait, up to 3 s; the height reports of the keyboard's slide do not. A dock
   still covered when a clean wait ends teaches the page that its browser leaves
   it covered (`isDockLeftCovered(win)`), and every later show works as on main.
-  A show under a pinch zoom, whose pan is the reader's, learns nothing.
+  In the show that learned it, a later pan to the dock before any input is put
+  back, as at every later show, and the page keeps what it learned. A show
+  under a pinch zoom, whose pan is the reader's, learns nothing.
   Otherwise, and after any touch or wheel once the reveal is over, the dock
   follows the part of the cover the pan leaves (`followsDockDeficit(win)`). A
   show for a field outside the dock follows it from the start. Where the layout
diff --git a/packages/core/src/keyboard/keyboardHeight.ts b/packages/core/src/keyboard/keyboardHeight.ts
index 45b3fb3b52e88..9d1849a9cf1be 100644
--- a/packages/core/src/keyboard/keyboardHeight.ts
+++ b/packages/core/src/keyboard/keyboardHeight.ts
@@ -662,13 +662,9 @@ function notifyDockReveal(): void {
   }
 }
 
-function learnDockLeftCovered(win: Window, covered: boolean): void {
-  if (docksLeftCovered.has(win) !== covered) {
-    if (covered) {
-      docksLeftCovered.add(win);
-    } else {
-      docksLeftCovered.delete(win);
-    }
+function learnDockLeftCovered(win: Window): void {
+  if (!docksLeftCovered.has(win)) {
+    docksLeftCovered.add(win);
     notifyDockReveal();
   }
 }
@@ -676,8 +672,8 @@ function learnDockLeftCovered(win: Window, covered: boolean): void {
 /**
  * Whether `win`'s browser was found to leave a fixed dock covered at a
  * keyboard show. A pan to the dock decides only its own show and teaches
- * nothing. A browser can pan at one show and not at the next. A late pan to
- * the dock after the lift, before any input, forgets it.
+ * nothing. A browser can pan at one show and not at the next. Once learned, it
+ * holds for the page.
  */
 export function isDockLeftCovered(win: Window): boolean {
   return docksLeftCovered.has(win);
@@ -720,14 +716,15 @@ export function __resetDockRevealForTest(win: Window): void {
 // The dock's watch: one decision per keyboard show for the dock's field. A
 // pan to the dock decides that show alone: no lift. A dock still covered when
 // the wait ends rises. With no touch or wheel in the wait, the page learns that
-// its browser leaves the dock covered. Only the show that learned it, before
-// any input, still meets a slow browser's pan: the lift then goes, and the page
-// forgets it. After a touch or a wheel, once the browser's reveal is over, the
+// its browser leaves the dock covered. In the show that learned it, a later pan
+// to the dock before any input is put back, as at every later show. After a
+// touch or a wheel, once the browser's reveal is over, the
 // dock follows the part of the cover that the pan leaves. So a reader's scroll
 // that moves the pan keeps the dock on the keyboard.
 function watchDock(
   win: Window,
   owns: (focused: HTMLElement) => boolean,
+  putBackTo: (top: number) => void,
 ): {
   report: (height: number) => boolean;
   input: () => void;
@@ -801,7 +798,7 @@ function watchDock(
       show = 'covered';
       coveredPan = getKeyboardPan(win) ?? 0;
       isClassifying = true;
-      learnDockLeftCovered(win, true);
+      learnDockLeftCovered(win);
     }
   };
   const restartSettle = () => {
@@ -881,11 +878,11 @@ function watchDock(
       }
       return true;
     }
+    // The module's own put-back measures from the opening report, before the
+    // lift moved the layout. So this show puts a pan to the dock back itself.
     if (show === 'covered' && isClassifying) {
       if (isRevealPan(pan, height) && pan > coveredPan + 0.5) {
-        show = 'revealed';
-        isClassifying = false;
-        learnDockLeftCovered(win, false);
+        putBackTo(coveredPan);
       }
       return true;
     }
@@ -925,9 +922,34 @@ export function watchRevealPan(
   {owns, onTouch, dock = false}: WatchRevealPanOptions,
 ): RevealPanWatch {
   const doc = win.document;
-  const dockWatch = dock ? watchDock(win, owns) : null;
   let atReport: {x: number; y: number; top: number; scale: number} | null =
     null;
+  // Pans the visual viewport back to `top`, without scrolling the document. It
+  // scrolls `anchor` into view, or a probe fixed at `top` in the layout
+  // viewport, which the pan does not move.
+  const putBackTo = (top: number, anchor?: Element | null) => {
+    const options: ScrollIntoViewOptions = {
+      block: 'start',
+      inline: 'nearest',
+      behavior: 'instant',
+    };
+    if (anchor != null) {
+      anchor.scrollIntoView(options);
+      return;
+    }
+    const probe = doc.createElement('div');
+    probe.style.position = 'fixed';
+    probe.style.left = '0';
+    probe.style.top = `${top}px`;
+    probe.style.width = '1px';
+    probe.style.height = '1px';
+    probe.style.visibility = 'hidden';
+    probe.style.pointerEvents = 'none';
+    (doc.body ?? doc.documentElement).append(probe);
+    probe.scrollIntoView(options);
+    probe.remove();
+  };
+  const dockWatch = dock ? watchDock(win, owns, top => putBackTo(top)) : null;
   let touchedSinceReport = false;
   const stopTouchStarts = watchTouchStarts(doc, () => {
     touchedSinceReport = true;
@@ -965,30 +987,7 @@ export function watchRevealPan(
         owns(focused)
       );
     },
-    putBack: anchor => {
-      const options: ScrollIntoViewOptions = {
-        block: 'start',
-        inline: 'nearest',
-        behavior: 'instant',
-      };
-      if (anchor != null) {
-        anchor.scrollIntoView(options);
-        return;
-      }
-      // A fixed element sits in the layout viewport, which the pan does not
-      // move: scrolling its top into view pans the visual viewport back.
-      const probe = doc.createElement('div');
-      probe.style.position = 'fixed';
-      probe.style.left = '0';
-      probe.style.top = `${atReport?.top ?? 0}px`;
-      probe.style.width = '1px';
-      probe.style.height = '1px';
-      probe.style.visibility = 'hidden';
-      probe.style.pointerEvents = 'none';
-      (doc.body ?? doc.documentElement).append(probe);
-      probe.scrollIntoView(options);
-      probe.remove();
-    },
+    putBack: anchor => putBackTo(atReport?.top ?? 0, anchor),
     dockReport: height => dockWatch?.report(height) ?? false,
     stop:
       dockWatch == null