@flamingo-stack/openframe-frontend-core 0.0.673 → 0.0.674-2431.7289.1

package/dist/utils/scroll-into-view.d.ts

@@ -61,6 +61,16 @@ export interface ScrollElementIntoViewOptions {
     /** Tween duration in ms (smooth only). Default 320. */
     durationMs?: number;
 }
+/** Nearest ancestor that is a *real* scroll container, or `null` when the
+ *  window/document is the scroller. Only `auto | scroll | overlay` count —
+ *  `clip` / `hidden` are intentionally excluded (a wrapper using `overflow-clip`
+ *  purely to round corners must let the scroll bubble to the page).
+ *
+ *  THE one rule for "what scrolls this element": `useScrollSpy` resolves the
+ *  scroller it listens to with it, so the section a spy highlights is the
+ *  section this helper scrolls to — inside a `<main overflow-y-auto>` shell as
+ *  much as on a window-scrolled page. */
+export declare function getScrollableAncestor(el: HTMLElement): HTMLElement | null;
 /**
  * Scroll the page so `target` lands at the top of the viewport (below sticky
  * chrome via `headerOffset`). SSR-safe; `null`/`undefined` target is a no-op so

package/dist/utils/scroll-into-view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scroll-into-view.d.ts","sourceRoot":"","sources":["../../src/utils/scroll-into-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,MAAM,WAAW,4BAA4B;IAC3C;+EAC2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;oFACgF;IAChF,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;6EAGyE;IACzE,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAsCD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,EACtC,OAAO,GAAE,4BAAiC,GACzC,IAAI,CA+EN"}
+{"version":3,"file":"scroll-into-view.d.ts","sourceRoot":"","sources":["../../src/utils/scroll-into-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,MAAM,WAAW,4BAA4B;IAC3C;+EAC2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;oFACgF;IAChF,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;6EAGyE;IACzE,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAqBD;;;;;;;;yCAQyC;AACzC,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,WAAW,GAAG,WAAW,GAAG,IAAI,CAWzE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,EACtC,OAAO,GAAE,4BAAiC,GACzC,IAAI,CA+EN"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.673",
+  "version": "0.0.674-2431.7289.1",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/chat/chat-message-enhanced.tsx

@@ -542,8 +542,17 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
             Avatar is INLINE in the name row below (2025-2026 chat
             pattern — Claude.ai, ChatGPT, Gemini, Perplexity).
             Legacy hanging-avatar layout (`absolute -left-16`) wasted
-            64px of gutter and clipped in narrow panels. */}
-        <div className="flex min-w-0 flex-col gap-[var(--spacing-system-xxs)]">
+            64px of gutter and clipped in narrow panels.
+
+            Single-column GRID, not `flex flex-col` — here, in the segment
+            stack below, in the thread's per-message wrapper and in the
+            card/video pair (entity-cards/dispatch): WebKit re-lays-out the
+            children of every nested column flexbox to measure them, so the
+            cost compounds per level. One 9-level Mingo reply took ~155ms of
+            layout per drawer-resize frame in Safari / the desktop WKWebView
+            vs ~9ms as grid (Chrome: ~2ms either way). Same gap and stretch,
+            no margin collapsing — visually identical. */}
+        <div className="grid min-w-0 grid-cols-1 gap-[var(--spacing-system-xxs)]">
           {/* Avatar + Name + Timestamp Row.
               Sizing rationale (per design-token measurements):
                 - Name uses `text-h3` = 14px mobile / 18px desktop.
@@ -604,7 +613,7 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
 
           {/* Message segments — hidden for system messages without content */}
           {(!isSystem || segments.length > 0) && (
-            <div className="flex flex-col gap-2">
+            <div className="grid grid-cols-1 gap-2">
               {segments.map((segment, index) => {
                 // The engine's streaming path (atomic-block memoization +
                 // fence tail-completion + aria-live) applies ONLY to the

package/src/components/chat/chat-message-list.tsx

@@ -1017,7 +1017,7 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
                   // thread without any stays byte-identical to before.
                   if (!ownedContent) return row;
                   return (
-                    <div key={message.id} className="flex w-full min-w-0 flex-col">
+                    <div key={message.id} className="grid w-full min-w-0 grid-cols-1">
                       {row}
                       {ownedContent}
                     </div>

package/src/components/chat/entity-cards/dispatch.tsx

@@ -2203,7 +2203,7 @@ export function ChatCardLoader({
       // Same 12px rhythm as the message renderer's block-sibling wrapper
       // (`my-3` in chat-message-enhanced) so card→player spacing matches
       // the spacing between any two hoisted blocks.
-      <div className="flex min-w-0 flex-col gap-3">
+      <div className="grid min-w-0 grid-cols-1 gap-3">
         {finish(entry.render(item, finalChatRef, renderOpts))}
         <ChatVideoEntityCard chatRef={videoRef} />
       </div>

package/src/components/docs/__tests__/use-scroll-spy.test.tsx

@@ -1,11 +1,21 @@
 import { act, renderHook } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { scrollElementIntoView } from '../../../utils/scroll-into-view';
 import { useScrollSpy } from '../use-scroll-spy';
 
+// The click's scroll is the shared tween; only its arguments matter here.
+// `getScrollableAncestor` stays real — it is what the spy resolves its scroller with.
+vi.mock('../../../utils/scroll-into-view', async importOriginal => ({
+  ...(await importOriginal()),
+  scrollElementIntoView: vi.fn(),
+}));
+
 /**
- * `useScrollSpy` highlights the section whose DOCUMENT-absolute top has passed
- * the offset line (not `offsetTop`, which is relative to a positioned
- * ancestor), and the last section once the page is scrolled to the bottom.
+ * `useScrollSpy` highlights the section whose top — measured in the SCROLLER's
+ * own coordinates (not `offsetTop`, which is relative to a positioned
+ * ancestor) — has passed the offset line, and the last section once the
+ * scroller is at the bottom. The scroller is the window on a plain page, and
+ * the nearest scroll container when an app shell scrolls a `<main>` instead.
  */
 
 const TOPS: Record<string, number> = { a: 300, b: 900, c: 1500 };
@@ -107,3 +117,153 @@ describe('useScrollSpy — syncHash', () => {
     expect(replaceState).not.toHaveBeenCalled();
   });
 });
+
+describe('useScrollSpy — a rail click', () => {
+  const sections = [{ id: 'a' }, { id: 'b' }, { id: 'c' }];
+
+  it('highlights the clicked section at once and scrolls it under the header offset', () => {
+    placeSections(0);
+    const { result } = renderHook(() => useScrollSpy(sections, { headerOffset: 96 }));
+    act(() => result.current.handleSectionClick('c'));
+    expect(result.current.activeSection).toBe('c');
+    expect(scrollElementIntoView).toHaveBeenCalledWith(created.get('c'), { headerOffset: 96 });
+  });
+
+  it('with syncHash, writes #section right away — replaceState, no history entry, no hashchange', () => {
+    const replaceState = vi.spyOn(window.history, 'replaceState').mockImplementation(() => {});
+    const pushState = vi.spyOn(window.history, 'pushState');
+    const hashchange = vi.fn();
+    window.addEventListener('hashchange', hashchange);
+    placeSections(0);
+    const { result } = renderHook(() => useScrollSpy(sections, { syncHash: true }));
+    act(() => result.current.handleSectionClick('b'));
+    expect(replaceState).toHaveBeenCalledWith(null, '', '/#b');
+    expect(pushState).not.toHaveBeenCalled();
+    expect(hashchange).not.toHaveBeenCalled();
+    window.removeEventListener('hashchange', hashchange);
+  });
+
+  it('without syncHash, a click leaves the URL alone', () => {
+    const replaceState = vi.spyOn(window.history, 'replaceState').mockImplementation(() => {});
+    placeSections(0);
+    const { result } = renderHook(() => useScrollSpy(sections));
+    act(() => result.current.handleSectionClick('b'));
+    expect(replaceState).not.toHaveBeenCalled();
+  });
+});
+
+describe('useScrollSpy — headerOffset', () => {
+  const sections = [{ id: 'a' }, { id: 'b' }, { id: 'c' }];
+
+  it('is the detection line too, so the highlight agrees with where a click lands', () => {
+    placeSections(0);
+    const { result } = renderHook(() => useScrollSpy(sections, { headerOffset: 50 }));
+    scrollTo(860); // 860 + 50 ≥ 900 → b
+    expect(result.current.activeSection).toBe('b');
+    scrollTo(840); // 890 < 900 → still a (the default 100 would already say b)
+    expect(result.current.activeSection).toBe('a');
+  });
+});
+
+/**
+ * An app shell that scrolls a fixed-height `<main overflow-y-auto>` instead of
+ * the window (OpenFrame's `AppLayout`): the window never scrolls and never
+ * emits `scroll`, so the spy must listen to the container and measure section
+ * tops relative to it — the shell's header sits ABOVE the container, so a
+ * viewport-relative top is off by that much.
+ */
+describe('useScrollSpy — inside a scroll container', () => {
+  const sections = [{ id: 'a' }, { id: 'b' }, { id: 'c' }];
+  /** The shell header above `<main>`: where the container starts in the viewport. */
+  const CONTAINER_TOP = 64;
+  let container: HTMLElement;
+  let containerScrollTop = 0;
+
+  function placeInContainer(scrollTop: number) {
+    for (const [id, top] of Object.entries(TOPS)) {
+      const el = created.get(id);
+      if (!el) throw new Error(`section ${id} not mounted`);
+      // Viewport-relative top = container's viewport top + (offset inside the container − its scrollTop).
+      vi.spyOn(el, 'getBoundingClientRect').mockReturnValue({ top: CONTAINER_TOP + top - scrollTop } as DOMRect);
+    }
+  }
+
+  function mountContainer(scrollHeight = 5000) {
+    container = document.createElement('main');
+    container.style.overflowY = 'auto';
+    document.body.append(container);
+    containerScrollTop = 0;
+    // jsdom lays nothing out: give the container the geometry of a scrolling <main>.
+    Object.defineProperty(container, 'scrollHeight', { configurable: true, value: scrollHeight });
+    Object.defineProperty(container, 'clientHeight', { configurable: true, value: 700 });
+    Object.defineProperty(container, 'scrollTop', {
+      configurable: true,
+      get: () => containerScrollTop,
+      set: (value: number) => {
+        containerScrollTop = value;
+      },
+    });
+    vi.spyOn(container, 'getBoundingClientRect').mockReturnValue({ top: CONTAINER_TOP } as DOMRect);
+    for (const id of Object.keys(TOPS)) {
+      const el = document.createElement('section');
+      el.id = id;
+      container.append(el);
+      created.set(id, el);
+    }
+    placeInContainer(0);
+    // The window stays parked: a window-bound spy would read these and see nothing.
+    Object.defineProperty(window, 'scrollY', { configurable: true, value: 0 });
+    Object.defineProperty(window, 'innerHeight', { configurable: true, value: 800 });
+    Object.defineProperty(document.documentElement, 'scrollHeight', { configurable: true, value: 800 });
+  }
+
+  function scrollContainerTo(scrollTop: number) {
+    container.scrollTop = scrollTop;
+    placeInContainer(scrollTop);
+    act(() => {
+      container.dispatchEvent(new Event('scroll'));
+      vi.advanceTimersByTime(150);
+    });
+  }
+
+  afterEach(() => container.remove());
+
+  it('follows the container scroll, measuring section tops in the container coordinates', () => {
+    mountContainer();
+    const { result } = renderHook(() => useScrollSpy(sections));
+    expect(result.current.activeSection).toBe('a');
+    scrollContainerTo(850); // 850 + 100 ≥ 900 → b (viewport top 114 alone would have said a)
+    expect(result.current.activeSection).toBe('b');
+    scrollContainerTo(250); // 350 ≥ 300 → a
+    expect(result.current.activeSection).toBe('a');
+  });
+
+  it('ignores the window: a window scroll event changes nothing', () => {
+    mountContainer();
+    const { result } = renderHook(() => useScrollSpy(sections));
+    scrollContainerTo(850);
+    expect(result.current.activeSection).toBe('b');
+    Object.defineProperty(window, 'scrollY', { configurable: true, value: 4000 });
+    act(() => {
+      window.dispatchEvent(new Event('scroll'));
+      vi.advanceTimersByTime(150);
+    });
+    expect(result.current.activeSection).toBe('b');
+  });
+
+  it('highlights the last section at the bottom of the container', () => {
+    mountContainer(2200);
+    const { result } = renderHook(() => useScrollSpy(sections));
+    scrollContainerTo(1500); // 700 + 1500 ≥ 2200 → bottom → c (its top, 1500, never passes 1600)
+    expect(result.current.activeSection).toBe('c');
+  });
+
+  it('syncHash follows the container scroll', () => {
+    const replaceState = vi.spyOn(window.history, 'replaceState').mockImplementation(() => {});
+    mountContainer();
+    renderHook(() => useScrollSpy(sections, { syncHash: true }));
+    scrollContainerTo(850);
+    scrollContainerTo(50); // 150 < 300: above section a → cleared
+    expect(replaceState.mock.calls.map(call => call[2])).toEqual(['/#b', '/']);
+  });
+});

package/src/components/docs/use-scroll-spy.ts

@@ -1,14 +1,14 @@
 'use client';
 
 import { useState, useRef, useCallback, useEffect, useMemo } from 'react';
-import { scrollElementIntoView } from '../../utils/scroll-into-view';
-
-// Single source for the sticky-chrome height. Used for BOTH the scroll target
-// offset (where a clicked section lands) AND the active-section detection
-// threshold (where the scroll listener flips highlight). They must match —
-// previously 100 vs 150 caused a 50px window where the indicator jumped to
-// the next section even though that section's top was still below the
-// clicked one's resting offset.
+import { getScrollableAncestor, scrollElementIntoView } from '../../utils/scroll-into-view';
+
+// Default sticky-chrome height. Used for BOTH the scroll target offset (where a
+// clicked section lands) AND the active-section detection threshold (where the
+// scroll listener flips highlight). They must match — previously 100 vs 150
+// caused a 50px window where the indicator jumped to the next section even
+// though that section's top was still below the clicked one's resting offset.
+// `headerOffset` overrides both at once, so they cannot drift apart.
 const SCROLL_OFFSET = 100;
 
 // Separator for the section-id key. A newline cannot occur inside an HTML id,
@@ -23,12 +23,19 @@ interface ScrollSpySection {
 
 export interface UseScrollSpyOptions {
   /**
-   * Keep the URL's `#hash` on the section being read as the user SCROLLS
-   * (`replaceState`: no history entry, and no `hashchange`, so
-   * `useScrollToHash` never re-scrolls to it). Above the first section the hash
-   * is cleared. Only a scroll writes it — mounting a page never adds a hash.
+   * Keep the URL's `#hash` on the section being read (`replaceState`: no
+   * history entry, and no `hashchange`, so `useScrollToHash` never re-scrolls
+   * to it) — as the user SCROLLS, and when a rail click scrolls for them.
+   * Above the first section the hash is cleared. Only a scroll or a click
+   * writes it — mounting a page never adds a hash.
    */
   syncHash?: boolean;
+  /**
+   * Sticky-chrome height in px: where a clicked section lands AND the line a
+   * section's top must pass to become the active one. One number for both, so
+   * the highlight agrees with where the click put the section. Default 100.
+   */
+  headerOffset?: number;
 }
 
 /** Point the URL's hash at `sectionId` (or clear it) without a history entry or a `hashchange`. */
@@ -39,6 +46,50 @@ function replaceHash(sectionId: string | null): void {
   window.history.replaceState(window.history.state, '', `${pathname}${search}${next}`);
 }
 
+/**
+ * The thing that scrolls the sections: the nearest real scroll container
+ * around them, or the window. Reads are routed through it so the same
+ * arithmetic serves both — the window is just the scroller whose visible area
+ * starts at viewport y = 0.
+ */
+interface Scroller {
+  target: HTMLElement | Window;
+  scrollTop: () => number;
+  /** Where the scroller's visible area starts, in viewport coordinates. */
+  viewportTop: () => number;
+  clientHeight: () => number;
+  scrollHeight: () => number;
+}
+
+/**
+ * Resolve the scroller from the first section, with the SAME rule
+ * `scrollElementIntoView` uses to pick where it scrolls (`getScrollableAncestor`).
+ * App shells that put page content in a fixed-height `<main overflow-y-auto>`
+ * (OpenFrame's `AppLayout`) never scroll the window: a window-bound spy there
+ * sees `scrollY` 0 forever and never gets a `scroll` event, so the first
+ * section stayed highlighted whatever was on screen. No such ancestor (a plain
+ * page, or the sections not rendered yet) → the window, as before.
+ */
+function resolveScroller(firstSection: HTMLElement | null): Scroller {
+  const container = firstSection ? getScrollableAncestor(firstSection) : null;
+  if (container) {
+    return {
+      target: container,
+      scrollTop: () => container.scrollTop,
+      viewportTop: () => container.getBoundingClientRect().top,
+      clientHeight: () => container.clientHeight,
+      scrollHeight: () => container.scrollHeight,
+    };
+  }
+  return {
+    target: window,
+    scrollTop: () => window.scrollY,
+    viewportTop: () => 0,
+    clientHeight: () => window.innerHeight,
+    scrollHeight: () => document.documentElement.scrollHeight,
+  };
+}
+
 interface UseScrollSpyReturn {
   activeSection: string;
   handleSectionClick: (sectionId: string) => void;
@@ -46,13 +97,18 @@ interface UseScrollSpyReturn {
 
 /**
  * Shared scroll spy hook for tracking active section based on scroll position.
- * Used by DocViewer for sticky section navigation.
+ * Used by DocViewer and TrustCenterPage for sticky section navigation.
+ *
+ * Listens to whatever actually scrolls the sections — the nearest scroll
+ * container, else the window (see `resolveScroller`) — and measures section
+ * tops in that scroller's own coordinates, which is exactly how
+ * `scrollElementIntoView` computes the target of a click.
  */
 export function useScrollSpy(
   sections: ScrollSpySection[] | undefined,
   options: UseScrollSpyOptions = {},
 ): UseScrollSpyReturn {
-  const { syncHash = false } = options;
+  const { syncHash = false, headerOffset = SCROLL_OFFSET } = options;
   const [activeSection, setActiveSection] = useState('');
   const isScrollingFromClick = useRef(false);
 
@@ -63,46 +119,63 @@ export function useScrollSpy(
   // of the dependency array.
   const sectionIdsKey = useMemo(() => sections?.map(s => s.id).join(ID_SEPARATOR) ?? '', [sections]);
 
-  const handleSectionClick = useCallback((sectionId: string) => {
-    const targetElement = document.getElementById(sectionId);
-    if (!targetElement) return;
+  const handleSectionClick = useCallback(
+    (sectionId: string) => {
+      const targetElement = document.getElementById(sectionId);
+      if (!targetElement) return;
 
-    isScrollingFromClick.current = true;
-    setActiveSection(sectionId);
+      isScrollingFromClick.current = true;
+      setActiveSection(sectionId);
+      // The click IS the reader's position now: say so in the URL right away
+      // rather than waiting for a scroll event the click guard below swallows.
+      if (syncHash) replaceHash(sectionId);
 
-    scrollElementIntoView(targetElement, { headerOffset: SCROLL_OFFSET });
+      scrollElementIntoView(targetElement, { headerOffset });
 
-    setTimeout(() => {
-      isScrollingFromClick.current = false;
-    }, 800);
-  }, []);
+      setTimeout(() => {
+        isScrollingFromClick.current = false;
+      }, 800);
+    },
+    [syncHash, headerOffset],
+  );
 
   useEffect(() => {
     const sectionIds = sectionIdsKey === '' ? [] : sectionIdsKey.split(ID_SEPARATOR);
     if (sectionIds.length === 0) return undefined;
 
+    // Pick the scroller ONCE per section set, like `scrollElementIntoView` does
+    // per call: the sections and their container render together, so the
+    // effect sees the final layout.
+    const scroller = resolveScroller(document.getElementById(sectionIds[0] ?? ''));
+
     // `fromScroll`: a real scroll settled (not the mount-time pass).
     const handleScroll = (fromScroll = false) => {
       if (isScrollingFromClick.current) return;
 
-      const scrollPosition = window.scrollY + SCROLL_OFFSET;
+      const scrollTop = scroller.scrollTop();
+      const viewportTop = scroller.viewportTop();
+      const scrollPosition = scrollTop + headerOffset;
+      // A section's top in the scroller's coordinates. `offsetTop` is relative
+      // to the nearest POSITIONED ancestor, which is neither the document nor
+      // the scroll container inside most layouts — measure from the viewport
+      // and translate.
+      const sectionTop = (element: HTMLElement) => element.getBoundingClientRect().top - viewportTop + scrollTop;
       let currentSection = sectionIds[0] ?? '';
 
       // At the bottom of the page the last sections can never reach the offset
       // line, so they would never highlight: the last one wins there. Only on a
       // page that actually SCROLLS — a short page is "at the bottom" at
-      // scrollY 0, which would otherwise highlight the last section on load.
-      const { scrollHeight } = document.documentElement;
-      const scrollable = scrollHeight > window.innerHeight + 2;
-      const atBottom = scrollable && window.innerHeight + window.scrollY >= scrollHeight - 2;
+      // scrollTop 0, which would otherwise highlight the last section on load.
+      const scrollHeight = scroller.scrollHeight();
+      const clientHeight = scroller.clientHeight();
+      const scrollable = scrollHeight > clientHeight + 2;
+      const atBottom = scrollable && clientHeight + scrollTop >= scrollHeight - 2;
       if (atBottom) {
         currentSection = sectionIds[sectionIds.length - 1] ?? currentSection;
       } else {
         for (let i = sectionIds.length - 1; i >= 0; i--) {
           const element = document.getElementById(sectionIds[i]);
-          // Document-absolute top: `offsetTop` is relative to the nearest
-          // POSITIONED ancestor, which is not the document inside most layouts.
-          if (element && scrollPosition >= element.getBoundingClientRect().top + window.scrollY) {
+          if (element && scrollPosition >= sectionTop(element)) {
             currentSection = sectionIds[i];
             break;
           }
@@ -113,8 +186,7 @@ export function useScrollSpy(
 
       if (syncHash && fromScroll) {
         const first = document.getElementById(sectionIds[0] ?? '');
-        const aboveFirst =
-          !atBottom && first !== null && scrollPosition < first.getBoundingClientRect().top + window.scrollY;
+        const aboveFirst = !atBottom && first !== null && scrollPosition < sectionTop(first);
         replaceHash(aboveFirst ? null : currentSection);
       }
     };
@@ -125,14 +197,14 @@ export function useScrollSpy(
       scrollTimer = setTimeout(() => handleScroll(true), 100);
     };
 
-    window.addEventListener('scroll', throttledScroll);
+    scroller.target.addEventListener('scroll', throttledScroll);
     handleScroll();
 
     return () => {
-      window.removeEventListener('scroll', throttledScroll);
+      scroller.target.removeEventListener('scroll', throttledScroll);
       clearTimeout(scrollTimer);
     };
-  }, [sectionIdsKey, syncHash]);
+  }, [sectionIdsKey, syncHash, headerOffset]);
 
   return { activeSection, handleSectionClick };
 }

package/src/components/help-center-pages/__tests__/trust-center-page.test.tsx

@@ -397,7 +397,7 @@ describe('TrustCenterPage', () => {
     expect(subprocessors.queryByText('Location')).toBeNull();
   });
 
-  it('anchors: a rail click puts #section in the URL through the shared same-page hash navigation (replace, not push)', () => {
+  it('anchors: a rail click highlights the section at once and puts #section in the URL (replace, not push)', () => {
     // The shared setup stubs `window.location` without an origin; give it one for this navigation.
     const stubbed = window.location;
     Object.defineProperty(window, 'location', {
@@ -417,6 +417,10 @@ describe('TrustCenterPage', () => {
       render(<TrustCenterPage initialData={makeData()} />);
       const rail = within(screen.getByRole('complementary', { name: 'Trust center sections' }));
       fireEvent.click(rail.getByRole('button', { name: 'Documents' }));
+      // The click IS the reader's position: the rail says so before any scroll
+      // event lands (inside a `<main overflow-y-auto>` shell none ever did).
+      expect(rail.getByRole('button', { name: 'Documents' })).toHaveAttribute('aria-current', 'location');
+      expect(rail.getByRole('button', { name: 'Compliance' })).not.toHaveAttribute('aria-current');
       expect(replaceState).toHaveBeenCalledWith(null, '', '/trust-center#documents');
       expect(pushState).not.toHaveBeenCalled();
     } finally {

package/src/components/help-center-pages/trust-center-page.tsx

@@ -43,7 +43,7 @@ import {
   type TrustCenterPublic,
   type TrustCenterSectionId,
 } from '../../types/trust-center';
-import { navigateSamePageHash, STICKY_HEADER_OFFSET_PX } from '../../utils/same-page-hash-nav';
+import { STICKY_HEADER_OFFSET_PX } from '../../utils/same-page-hash-nav';
 import { useScrollSpy } from '../docs/use-scroll-spy';
 import { FaqSection } from '../faq/faq-section';
 import { PageShell } from '../layout/article-detail-layout';
@@ -178,16 +178,20 @@ export function TrustCenterPage({
   });
 
   const sections = useMemo(() => (data ? visibleSections(data) : []), [data]);
-  // Anchors: the shared same-page hash navigation (the FAQ section's pattern).
-  // A rail click puts `#section` in the URL (`replace`: the rail is a table of
-  // contents, not a navigation step) and scrolls below the sticky header; a
-  // visit that ARRIVES with `#section`, and back/forward, scroll there once the
-  // sections have rendered. The scroll spy lights the rail and, as the reader
-  // scrolls, keeps the URL's hash on the section in view (`syncHash`).
-  const { activeSection } = useScrollSpy(sections, { syncHash: true });
-  const handleSectionClick = useCallback((sectionId: string) => {
-    navigateSamePageHash(`#${sectionId}`, { headerOffset: STICKY_HEADER_OFFSET_PX, history: 'replace' });
-  }, []);
+  // Anchors. The scroll spy lights the rail from whatever scrolls the sections
+  // (the window, or a host shell's `<main overflow-y-auto>` — OpenFrame's
+  // `AppLayout`) and keeps the URL's hash on the section in view (`syncHash`;
+  // `replace`: the rail is a table of contents, not a navigation step). A rail
+  // click goes through the spy too: it highlights the section at once, writes
+  // `#section` and scrolls it below the sticky header — the SAME offset the
+  // spy's detection line uses, so the highlight agrees with where the section
+  // landed. A visit that ARRIVES with `#section`, and back/forward, scroll
+  // there once the sections have rendered (`hashchange`, which `replaceState`
+  // never fires — so a click never re-scrolls through that path).
+  const { activeSection, handleSectionClick } = useScrollSpy(sections, {
+    syncHash: true,
+    headerOffset: STICKY_HEADER_OFFSET_PX,
+  });
   useScrollToHash(sections.length > 0 ? sections.map(section => section.id).join('|') : null, {
     headerOffset: STICKY_HEADER_OFFSET_PX,
   });

package/src/components/navigation/sticky-section-nav.tsx

@@ -66,6 +66,9 @@ export function StickySectionNav({
           {/* Navigation button */}
           <button
             onClick={() => onSectionClick(section.id)}
+            // The ribbon is the visual; this is the same state for assistive
+            // tech (a table of contents marks the reader's current location).
+            aria-current={activeSection === section.id ? 'location' : undefined}
             className="relative flex flex-1 cursor-pointer items-center gap-2 px-3 py-2"
           >
             <span

package/src/stories/TrustCenterPage.stories.tsx

@@ -1,9 +1,12 @@
 import type { Meta, StoryObj } from '@storybook/nextjs-vite';
+import { fn } from 'storybook/test';
 import {
   TRUST_CENTER_FIXTURE_FAQ,
   makeTrustCenterData,
 } from '../components/help-center-pages/__fixtures__/trust-center';
 import { TrustCenterPage } from '../components/help-center-pages/trust-center-page';
+import { ChartDonutIcon, QuestionCircleIcon } from '../components/icons-v2-generated';
+import { AppLayout } from '../components/navigation/app-layout';
 
 // Stories pass `initialData`, so the page never fetches. The shared fixture
 // computes its instants when called, so the "monitored" story stays inside its window.
@@ -93,6 +96,41 @@ export const NotConnected: Story = {
   },
 };
 
+/**
+ * Embedded in an app shell (OpenFrame's `AppLayout`), where the page content
+ * scrolls inside a fixed-height `<main overflow-y-auto>` and the window never
+ * scrolls. The section rail must still follow the reader: the scroll spy
+ * listens to that container, not the window.
+ */
+export const InAppShell: Story = {
+  args: { shell: false, backButton: { label: 'Back to Help Center', href: '/help-center' } },
+  render: args => (
+    <AppLayout
+      sidebarConfig={{
+        items: [
+          { id: 'dashboard', label: 'Dashboard', icon: <ChartDonutIcon size={24} />, path: '/dashboard' },
+          {
+            id: 'help-center',
+            label: 'Help Center',
+            icon: <QuestionCircleIcon size={24} />,
+            path: '/help-center',
+            section: 'secondary',
+            isActive: true,
+          },
+        ],
+        onNavigate: fn(),
+        onToggleMinimized: fn(),
+      }}
+      headerProps={{ showUser: true, userName: 'Alex Developer', userEmail: 'alex@openframe.dev' }}
+      mobileBurgerMenuProps={{ user: { userName: 'Alex Developer', userEmail: 'alex@openframe.dev' } }}
+    >
+      <div className="page-shell-content">
+        <TrustCenterPage {...args} />
+      </div>
+    </AppLayout>
+  ),
+};
+
 /** Certified framework with a published percent (progress ring + report period). */
 export const CertifiedWithPercent: Story = {
   args: {

package/src/utils/scroll-into-view.ts

@@ -85,8 +85,13 @@ const easeOutCubic = (t: number): number => 1 - Math.pow(1 - t, 3);
 /** Nearest ancestor that is a *real* scroll container, or `null` when the
  *  window/document is the scroller. Only `auto | scroll | overlay` count —
  *  `clip` / `hidden` are intentionally excluded (a wrapper using `overflow-clip`
- *  purely to round corners must let the scroll bubble to the page). */
-function getScrollableAncestor(el: HTMLElement): HTMLElement | null {
+ *  purely to round corners must let the scroll bubble to the page).
+ *
+ *  THE one rule for "what scrolls this element": `useScrollSpy` resolves the
+ *  scroller it listens to with it, so the section a spy highlights is the
+ *  section this helper scrolls to — inside a `<main overflow-y-auto>` shell as
+ *  much as on a window-scrolled page. */
+export function getScrollableAncestor(el: HTMLElement): HTMLElement | null {
   for (let node = el.parentElement; node; node = node.parentElement) {
     const overflowY = getComputedStyle(node).overflowY;
     if (