@flamingo-stack/openframe-frontend-core 0.0.209 → 0.0.210-snapshot.20260528032637

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

@@ -0,0 +1,63 @@
+/**
+ * `scrollElementIntoView` — canonical "smooth scroll element to top
+ * of viewport, account for sticky chrome, optionally adjust for
+ * known layout shifts" helper.
+ *
+ * Before this util existed, ~3 different call sites in the lib + hub
+ * had the same 5-line snippet copy-pasted with subtle differences:
+ *
+ *   - `useUnifiedNav` same-URL re-scroll branch (hub)
+ *   - `<HelpCenterCard>` click-to-expand (lib, with cross-row
+ *     layout-shift adjustment)
+ *   - Future ticket-row / docs anchor scrolls
+ *
+ * The canonical pattern is `window.scrollTo({top, behavior:'smooth'})`
+ * with a pre-computed pixel target — NOT `element.scrollIntoView()`.
+ * Pre-computing the target lets the browser run a clean uninterrupted
+ * smooth animation to a fixed pixel value. `scrollIntoView` re-targets
+ * continuously as the page layout shifts during the animation, which
+ * causes visible jitter when content above the target is also moving
+ * (a sibling collapsing, an async image loading, …).
+ *
+ * The `adjustTargetY` callback is the escape hatch for cases where
+ * the consumer KNOWS about an upcoming layout shift and can compute
+ * the correct FINAL target before the animation starts. Example: in
+ * `HelpCenterCard`, clicking row B while row A above is currently
+ * expanded — A's drawer collapses simultaneously with B's expansion,
+ * shifting B's tile up by A's drawer height. The consumer passes
+ * `adjustTargetY: raw => raw - getAboveDrawerHeight()` and the
+ * browser smooth-scrolls to the post-collapse position directly.
+ */
+export interface ScrollElementIntoViewOptions {
+    /** Pixels to subtract from the target element's `top` so it lands
+     *  BELOW sticky chrome. Defaults to 0. Pass `96` (matches
+     *  `scroll-mt-24`) for the standard hub header offset. */
+    headerOffset?: number;
+    /** Scroll animation style. Defaults to `'smooth'`. Use `'instant'`
+     *  for imperative jumps where animation would feel laggy (deep
+     *  link land, programmatic focus moves). */
+    behavior?: ScrollBehavior;
+    /** Optional adjustment applied to the computed pixel target. The
+     *  callback receives the "raw" Y (`element.top + scrollY -
+     *  headerOffset`) and returns the FINAL pixel target. Use this
+     *  when the caller knows about a layout shift that will happen
+     *  between the call and the animation completing — the browser's
+     *  smooth-scroll commits to a single pixel value, so providing the
+     *  post-shift target up front lands the element correctly even as
+     *  content above it moves. */
+    adjustTargetY?: (rawTargetY: number) => number;
+}
+/**
+ * Scroll the page so `target` lands at the top of the viewport,
+ * accounting for sticky chrome via `headerOffset`. Returns void; the
+ * scroll runs async via the browser's smooth-scroll engine.
+ *
+ * Accepts:
+ *   - `HTMLElement` — direct reference (most common from `useRef`).
+ *   - `null` / `undefined` — no-op so callers can pass refs without
+ *     defensive branching.
+ *
+ * SSR-safe: short-circuits when `window` is undefined.
+ */
+export declare function scrollElementIntoView(target: HTMLElement | null | undefined, options?: ScrollElementIntoViewOptions): void;
+//# sourceMappingURL=scroll-into-view.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-into-view.d.ts","sourceRoot":"","sources":["../../src/utils/scroll-into-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,WAAW,4BAA4B;IAC3C;;8DAE0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;gDAE4C;IAC5C,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB;;;;;;;kCAO8B;IAC9B,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAA;CAC/C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,EACtC,OAAO,GAAE,4BAAiC,GACzC,IAAI,CAON"}

package/package.json

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

package/src/components/chat/entity-cards/blog-card.tsx

@@ -19,6 +19,7 @@
  */
 
 import React, { useState } from 'react'
+import { Eye } from 'lucide-react'
 import Image from '../../../embed-shims/next-image'
 import { StatusBadge } from '../../ui/status-badge'
 import { cn } from '../../../utils/cn'
@@ -235,22 +236,30 @@ export function BlogCard({
             </p>
           </div>
 
-          {/* Footer: author + date (simplified — no hub BlogMeta dep). */}
-          <div className="mt-auto flex items-center gap-2 text-sm text-ods-text-secondary">
-            {post.author_avatar ? (
-              <Image
-                src={post.author_avatar}
-                alt={post.author_name || ''}
-                width={32}
-                height={32}
-                className="rounded-full"
-                unoptimized
-              />
-            ) : null}
-            <span className="truncate">
-              {post.author_name || 'Anonymous'}
-              {dateStr ? <> · {dateStr}</> : null}
-            </span>
+          <div className="mt-auto flex items-center justify-between gap-2 text-sm text-ods-text-secondary">
+            <div className="flex items-center gap-2 min-w-0">
+              {post.author_avatar ? (
+                <Image
+                  src={post.author_avatar}
+                  alt={post.author_name || ''}
+                  width={32}
+                  height={32}
+                  className="rounded-full shrink-0"
+                  unoptimized
+                />
+              ) : null}
+              <span className="truncate">
+                {post.author_name || 'Anonymous'}
+                {dateStr ? <> · {dateStr}</> : null}
+              </span>
+            </div>
+            <div
+              className="flex items-center gap-1 shrink-0"
+              aria-label={`View count: ${(post.view_count ?? 0).toLocaleString('en-US')} views`}
+            >
+              <Eye className="w-4 h-4 shrink-0" />
+              <span>{(post.view_count ?? 0).toLocaleString('en-US')}</span>
+            </div>
           </div>
         </div>
       </a>

package/src/components/chat/hooks/use-chat-identity.ts

@@ -8,8 +8,9 @@
  * (attachment button, drawer composer, /tickets gate) on chat-side
  * identity tiers WITHOUT sending a chat message first.
  *
- * Server-side parity: the route at `/api/chat/identity` runs the same
- * 3-tier `requireChatAuth` chain the chat itself uses.
+ * Server-side parity: the host's identity endpoint (hub default
+ * `/api/auth/identity`, override via `runtime.endpoints.identityUrl`)
+ * runs the same 3-tier `requireChatAuth` chain the chat itself uses.
  * `attachmentsEnabled` is computed server-side as
  * `authTier !== 'anon' AND isSelfScopedSource(source)` — single
  * source of truth, consumers don't combine the fields themselves.
@@ -27,7 +28,7 @@
  *   3. The fetch is cheap and short — no perf justification for a
  *      cache layer
  *
- * Endpoint URL: read from `useRequiredChatRuntime().endpoints.chatIdentityUrl`
+ * Endpoint URL: read from `useRequiredChatRuntime().endpoints.identityUrl`
  * so embedded apps with their own reverse-proxy topology can override.
  */
 
@@ -37,9 +38,9 @@ import { chatAuthedFetch } from '../utils/chat-authed-fetch'
 import { getChatProxyAuth } from '../utils/chat-proxy-auth-storage'
 
 /**
- * Wire-shape for the `/api/chat/identity` route response. Mirrors
- * the hub's `ChatIdentityResponse` (in `app/api/chat/identity/route.ts`)
- * — kept in sync there. Lib-side declaration so the chat panel can
+ * Wire-shape for the identity route response. Mirrors the hub's
+ * `ChatIdentityResponse` (in `app/api/auth/identity/route.ts`) —
+ * kept in sync there. Lib-side declaration so the chat panel can
  * compile without depending on hub-internal types.
  */
 export interface ChatIdentityResponse {
@@ -87,7 +88,7 @@ const ANON_DEFAULTS: ChatIdentityResponse = {
 
 export function useChatIdentity(): ChatIdentitySurface {
   const runtime = useRequiredChatRuntime()
-  const url = runtime.endpoints.chatIdentityUrl
+  const url = runtime.endpoints.identityUrl
   // `getChatProxyAuth()` reads localStorage every render. If the user
   // pastes bearer creds mid-session (via the `/debug` creds bar),
   // their email arrives here and the effect's dep changes → refetch.

package/src/components/footer-waitlist-button.tsx

@@ -1,6 +1,7 @@
 'use client';
 
-import { usePathname, useRouter } from '../embed-shims/next-navigation';
+import { useRouter } from '../embed-shims/next-navigation';
+import { useChatRuntime } from '../contexts/chat-runtime-context';
 import { useCallback } from 'react';
 import { OpenFrameLogo } from './icons';
 import { Button } from './ui/button';
@@ -11,27 +12,43 @@ export interface FooterWaitlistButtonProps {
 
 /**
  * Small wrapper around JoinWaitlistButton for use inside the footer.
- * Provides a default click handler that scrolls/focuses the wait-list form
- * if the user is already on /waitlist; otherwise navigates to it.
+ *
+ * Routes through the host's unified-navigation hook
+ * (`runtime.navigation.navigate`) when a `ChatRuntimeContext` is
+ * mounted — that's the same path EVERY other in-app navigation
+ * surface uses (source chips, inline cards, search-autocomplete,
+ * action cards). One rule, one decision tree across the whole app.
+ * The hub's `HubRuntimeProvider` wires `navigate` to its `useUnifiedNav`
+ * helper, so this button picks up cross-platform new-tab decisions,
+ * same-URL re-scroll handling, embed-mode short-circuiting, and any
+ * future host-side nav rules for free.
+ *
+ * Falls back to the embed-shim's `router.push` when no runtime is
+ * mounted (third-party embedders who haven't set up
+ * `ChatRuntimeContext` — the lib stays usable without forcing them
+ * to wire the full chat-runtime).
+ *
+ * Target URL: `/waitlist#top`. `#top` is the canonical "scroll to
+ * page top" anchor — the destination page has an explicit
+ * `<div id="top">` at the top of `<main>` so native browser anchor
+ * scroll works in every browser regardless of the HTML5 magic-anchor
+ * behavior.
  */
 export function FooterWaitlistButton({ className }: FooterWaitlistButtonProps) {
   const router = useRouter();
-  const pathname = usePathname();
+  const runtime = useChatRuntime();
 
   const handleClick = useCallback(() => {
-    if (pathname?.startsWith('/waitlist')) {
-      const anchor = document.getElementById('waitlist-form');
-      if (anchor) {
-        anchor.scrollIntoView({ behavior: 'smooth', block: 'center' } as any);
-        setTimeout(() => {
-          const input = anchor.querySelector('input[type="email"]') as HTMLInputElement | null;
-          input?.focus();
-        }, 400);
-        return;
-      }
+    const href = '/waitlist#top';
+    // Prefer the host's unified-nav callback (hub-wired
+    // `useUnifiedNav`). Falls back to the embed-shim's router when
+    // the host hasn't provided one.
+    if (runtime?.navigation?.navigate) {
+      const handled = runtime.navigation.navigate({ href });
+      if (handled) return;
     }
-    router.push('/waitlist#waitlist-form');
-  }, [pathname, router]);
+    router.push(href);
+  }, [router, runtime]);
 
   return (
     <Button 

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

@@ -2,6 +2,7 @@
 
 import React, { useEffect, useState, useCallback, useRef } from 'react'
 import { cn } from '../../utils'
+import { scrollElementIntoView } from '../../utils/scroll-into-view'
 
 export interface StickyNavSection {
   id: string
@@ -97,7 +98,10 @@ export function useSectionNavigation(
   const isScrollingFromClick = useRef(false)
   const { offset = 100 } = options || {}
 
-  // Handle click - just scroll to the element
+  // Handle click - scroll to the element via the canonical helper.
+  // The `offset` prop maps to `headerOffset` (sticky chrome above the
+  // section nav); same smooth-scroll mechanics every other anchor
+  // surface in the app uses.
   const handleSectionClick = useCallback((sectionId: string) => {
     const targetElement = document.getElementById(sectionId)
     if (!targetElement) return
@@ -106,9 +110,7 @@ export function useSectionNavigation(
     isScrollingFromClick.current = true
     setActiveSection(sectionId)
 
-    // Scroll to element
-    const top = targetElement.offsetTop - offset
-    window.scrollTo({ top, behavior: 'smooth' })
+    scrollElementIntoView(targetElement, { headerOffset: offset })
 
     // Allow scroll spy again after scroll completes
     setTimeout(() => {

package/src/components/tickets/help-center-card.tsx

@@ -15,8 +15,10 @@
  * is a SIBLING of the toggle button, not nested inside it.
  */
 
+import { useCallback, useRef } from 'react'
 import { StatusBadge, type StatusBadgeProps } from '../ui'
 import { formatRelativeTime } from '../../utils/date-utils'
+import { scrollElementIntoView } from '../../utils/scroll-into-view'
 import { getStatusColorScheme } from '../chat/utils/agent-status-message'
 import { DevCardRowContent } from '../shared/dev-section/dev-card-row'
 import {
@@ -26,6 +28,23 @@ import {
 import type { AnyTicket } from './types'
 import { isOptimistic } from './types'
 
+/** Sticky page-chrome offset, applied two ways from this ONE constant:
+ *
+ *   1. As `scrollMarginTop` inline style on the wrapper — so any
+ *      anchor-driven or `scrollIntoView()`-driven scroll (browser
+ *      `#hash` navigation, Tab-focus into the card) lands BELOW the
+ *      sticky header.
+ *   2. As `headerOffset` passed to `scrollElementIntoView(...)` — for
+ *      the click-to-expand `window.scrollTo` path, which pre-computes
+ *      its target pixel and ignores CSS `scroll-margin-top`.
+ *
+ *  Single source of truth: change 96 here and BOTH paths follow. The
+ *  previous code combined a `scroll-mt-24` (=96px) Tailwind class
+ *  with this constant — two declarations, one comment binding them,
+ *  drift hazard. Now there's nothing to keep in sync.
+ */
+const STICKY_HEADER_OFFSET_PX = 96
+
 export interface HelpCenterCardProps {
   ticket: AnyTicket
   expanded: boolean
@@ -72,6 +91,39 @@ export function HelpCenterCard({
   const isExpandable = !optimistic
   const isExpanded = expanded && isExpandable
 
+  // Scroll-on-click — delegates to the canonical `scrollElementIntoView`
+  // helper with a cross-row layout-shift `adjustTargetY` callback. The
+  // helper owns the smooth-scroll mechanics + sticky-chrome offset; we
+  // pass the consumer-specific knowledge ("a sibling drawer above me
+  // is about to collapse — subtract its height from the target Y").
+  //
+  // Cross-row gotcha: if ANOTHER row above this one is currently
+  // expanded, its drawer collapses simultaneously with our toggle.
+  // The collapse shrinks the page above our row → our final Y is
+  // HIGHER than the current `rect.top`. By pre-subtracting the
+  // collapsing drawer's height we land at the post-shift position
+  // cleanly, without scrollIntoView's mid-animation drift.
+  const rowRef = useRef<HTMLDivElement | null>(null)
+  const handleClick = useCallback(() => {
+    onToggle(ticket.id)
+    scrollElementIntoView(rowRef.current, {
+      headerOffset: STICKY_HEADER_OFFSET_PX,
+      adjustTargetY: (raw) => {
+        if (!rowRef.current) return raw
+        const expandedDrawer = document.querySelector(
+          'div[id^="help-center-drawer-"]',
+        )
+        if (!(expandedDrawer instanceof HTMLElement)) return raw
+        const drawerRect = expandedDrawer.getBoundingClientRect()
+        const myRect = rowRef.current.getBoundingClientRect()
+        // Only adjust when the drawer is ABOVE us. Drawers below us
+        // don't shift our position when they collapse.
+        if (drawerRect.bottom > myRect.top) return raw
+        return raw - drawerRect.height
+      },
+    })
+  }, [onToggle, ticket.id])
+
   const rightBadges = (
     <>
       <StatusBadge
@@ -93,12 +145,14 @@ export function HelpCenterCard({
 
   return (
     <div
+      ref={rowRef}
+      style={{ scrollMarginTop: STICKY_HEADER_OFFSET_PX }}
       className={`border-b border-ods-border last:border-b-0 ${optimistic ? 'opacity-60' : ''}`}
       aria-busy={optimistic || undefined}
     >
       <button
         type="button"
-        onClick={isExpandable ? () => onToggle(ticket.id) : undefined}
+        onClick={isExpandable ? handleClick : undefined}
         disabled={!isExpandable}
         aria-expanded={isExpandable ? isExpanded : undefined}
         aria-controls={isExpanded ? `help-center-drawer-${ticket.id}` : undefined}

package/src/components/tickets/help-center-list.tsx

@@ -264,7 +264,15 @@ function HelpCenterListAuthed({
               />
             )
           ) : (
-            <div className="bg-ods-card border border-ods-border rounded-[6px] overflow-hidden w-full">
+            // `overflow-clip` (NOT `overflow-hidden`) — both visually
+            // clip the rounded corners, but `hidden` makes the element
+            // a "scroll container" per CSSOM spec, which causes
+            // `scrollIntoView` calls inside (`<HelpCenterCard>` click
+            // handlers) to try scrolling THIS div (can't, overflow
+            // hidden) instead of bubbling up to the window. `clip`
+            // keeps the visual clip but NOT the scroll-container
+            // status, so click-to-scroll actually moves the page.
+            <div className="bg-ods-card border border-ods-border rounded-[6px] overflow-clip w-full">
               {merged.map((ticket) => (
                 <HelpCenterCard
                   key={ticket.id}

package/src/components/tickets/ticket-detail-drawer.tsx

@@ -212,9 +212,16 @@ function TicketTimelinePanel({ ticket }: { ticket: AnyTicket }) {
   return (
     <div className="bg-ods-card border border-ods-border rounded-[6px] overflow-hidden w-full">
       {/* Customer-authored description + any legacy `---`-joined
-          comments. Original message gets a special role label; legacy
-          updates get "Update N" or "Resolution". Timestamp matches the
-          ticket's creation time when available. */}
+          comments. Always rendered ABOVE the engagement timeline as
+          "Original message" because the server's intake-burst filter
+          (see `filterCustomerVisibleTimeline` in
+          `hubspot-conversations-utils.ts`) drops the customer's first
+          message from engagements when it was part of the HubSpot
+          Custom Channel bot intake — bodyTurns IS the canonical
+          original for those tickets. For tickets created without bot
+          intake (admin-created, email channel) bodyTurns shows the
+          manually-entered description and engagements show subsequent
+          replies — same flow, no duplication. */}
       {bodyTurns.map((turn, i) => {
         const isResolution = turn.startsWith('[Resolution]')
         const role =
@@ -315,11 +322,19 @@ function TicketTimelinePanel({ ticket }: { ticket: AnyTicket }) {
           avatarSrc = undefined
         }
 
+        // Role label: every engagement is a customer-visible
+        // Conversations message (customer ↔ agent on the Custom
+        // Channel). There are no internal Notes on this surface
+        // anymore — the read path explicitly filters them. So
+        // "Reply" for BOTH sides. The previous "Note" label for
+        // support bubbles was a legacy artifact from when Notes
+        // were rendered and made customers think their support
+        // engineer was leaving internal comments on their ticket.
         return (
           <ConversationCardRow
             key={eng.id}
             author={author}
-            role={isCustomer ? 'Reply' : 'Note'}
+            role="Reply"
             avatarSrc={avatarSrc}
             timestamp={eng.createdAt}
             body={stripAttachmentsPreamble(eng.body ?? '')}

package/src/components/tickets/ticket-row.tsx

@@ -18,7 +18,7 @@
  *      rendered only when this row is the expanded one.
  */
 
-import { useEffect, useRef } from 'react'
+import { useCallback, useRef } from 'react'
 import {
   Collapsible,
   CollapsibleContent,
@@ -28,6 +28,7 @@ import {
   type ChatTicketItemData,
 } from '../chat/entity-cards/chat-ticket-item'
 import { formatRelativeTime } from '../../utils/date-utils'
+import { scrollElementIntoView } from '../../utils/scroll-into-view'
 import {
   TicketDetailDrawer,
   type TicketDetailDrawerProps,
@@ -64,25 +65,35 @@ export function TicketRow({
   // arrived yet, so action targets would be undefined.
   const optimistic = isOptimistic(ticket)
 
-  // Scroll the row's summary tile to the top of the viewport when the
-  // user expands it. Without this, expanding a row near the bottom of
-  // the viewport leaves most of the drawer (timeline + composer)
-  // hidden — the user has to scroll manually to see what they just
-  // opened.
+  // Scroll the clicked card to the top of the viewport. Every click
+  // scrolls — first-click expansion, same-row re-click, cross-row
+  // switch. The clicked card lands at the top.
   //
-  // Uses smooth-scroll + `block: 'start'` so the tile lands at the top
-  // edge. Two RAFs let the Collapsible's height animation start before
-  // we measure the row position, otherwise the scroll lands at the
-  // pre-expansion position.
+  // Cross-row gotcha: if ANOTHER row above this one is currently
+  // expanded, its drawer is about to collapse simultaneously with our
+  // toggle. We pre-subtract its height from the target Y so the
+  // smooth-scroll lands at the FINAL post-collapse position cleanly.
+  // Same pattern as `<HelpCenterCard>` — the only diff is the drawer
+  // id prefix (`ticket-drawer-` vs `help-center-drawer-`).
   const rowRef = useRef<HTMLDivElement | null>(null)
-  useEffect(() => {
-    if (!expanded || optimistic) return
-    requestAnimationFrame(() => {
-      requestAnimationFrame(() => {
-        rowRef.current?.scrollIntoView({ behavior: 'smooth', block: 'start' })
-      })
+  const handleClick = useCallback(() => {
+    onToggle(ticket.id)
+    scrollElementIntoView(rowRef.current, {
+      adjustTargetY: (raw) => {
+        if (!rowRef.current) return raw
+        const expandedDrawer = document.querySelector(
+          'div[id^="ticket-drawer-"]',
+        )
+        if (!(expandedDrawer instanceof HTMLElement)) return raw
+        const drawerRect = expandedDrawer.getBoundingClientRect()
+        const myRect = rowRef.current.getBoundingClientRect()
+        // Only adjust when the drawer is ABOVE us. Drawers below
+        // don't shift our position when they collapse.
+        if (drawerRect.bottom > myRect.top) return raw
+        return raw - drawerRect.height
+      },
     })
-  }, [expanded, optimistic])
+  }, [onToggle, ticket.id])
 
   const tileData: ChatTicketItemData = {
     id: ticket.id,
@@ -112,14 +123,14 @@ export function TicketRow({
   }
 
   return (
-    <div ref={rowRef} className="scroll-mt-4">
+    <div ref={rowRef} className="scroll-mt-24">
       <Collapsible
         open={expanded && !optimistic}
         className="border-b border-ods-border last:border-b-0"
       >
       <ChatTicketItem
         ticket={tileData}
-        onClick={optimistic ? undefined : onToggle}
+        onClick={optimistic ? undefined : handleClick}
         aria-expanded={expanded && !optimistic}
         aria-controls={`ticket-drawer-${ticket.id}`}
       />

package/src/contexts/chat-runtime-context.tsx

@@ -62,12 +62,15 @@ export interface ChatRuntime {
      *      relative `/api/storage/view/chat-attachments/` is sufficient
      *      (same-origin); embedders supply an absolute hub URL so the
      *      browser can fetch cross-origin.
-     *    - `chatIdentityUrl` — GET endpoint the `useChatIdentity` hook
+     *    - `identityUrl` — GET endpoint the `useChatIdentity` hook
      *      hits to learn the `{authTier, source, attachmentsEnabled}`
-     *      capability bag for the current session. */
+     *      capability bag for the current session. Used beyond chat
+     *      (tickets / contact form / any embedded surface that needs
+     *      to identify the proxied customer), so the name has no
+     *      "chat" prefix even though the consuming hook still does. */
     attachmentUploadUrl: string
     attachmentViewUrlPrefix: string
-    chatIdentityUrl: string
+    identityUrl: string
     /** Optional URL prefix for the image proxy (`<prefix>?url=<external>`).
      *  When unset, lib's `getProxiedImageUrl` returns the original URL
      *  unchanged. Hub default: '/api/image-proxy'. Embedders that don't

package/src/stories/EmbeddableChat.stories.tsx

@@ -35,7 +35,7 @@ function createMockRuntime(): ChatRuntime {
       buildListUrl: () => null,
       attachmentUploadUrl: '/__story__/upload',
       attachmentViewUrlPrefix: '/__story__/view/',
-      chatIdentityUrl: '/__story__/identity',
+      identityUrl: '/__story__/identity',
     },
     navigation: {
       mode: 'embed',

package/src/utils/index.ts

@@ -200,3 +200,15 @@ export { fetchPriorityProp, type FetchPriorityValue } from './fetch-priority'
 // server-safe (no JSX, no contexts/* imports); imported by route-page
 // `metadata` exports + the shared `<DevSectionView>` chrome.
 export * from './dev-sections'
+
+// Canonical "smooth scroll element into view with sticky-chrome
+// offset" helper. Single source of truth across the lib + hub for
+// pre-computed-target scrolling — see `scroll-into-view.ts` for the
+// rationale (TL;DR: window.scrollTo({top, behavior:'smooth'}) with a
+// pre-computed pixel value avoids the mid-animation jitter that
+// `element.scrollIntoView()` produces when layout shifts during the
+// scroll).
+export {
+  type ScrollElementIntoViewOptions,
+  scrollElementIntoView,
+} from './scroll-into-view'

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

@@ -0,0 +1,74 @@
+/**
+ * `scrollElementIntoView` — canonical "smooth scroll element to top
+ * of viewport, account for sticky chrome, optionally adjust for
+ * known layout shifts" helper.
+ *
+ * Before this util existed, ~3 different call sites in the lib + hub
+ * had the same 5-line snippet copy-pasted with subtle differences:
+ *
+ *   - `useUnifiedNav` same-URL re-scroll branch (hub)
+ *   - `<HelpCenterCard>` click-to-expand (lib, with cross-row
+ *     layout-shift adjustment)
+ *   - Future ticket-row / docs anchor scrolls
+ *
+ * The canonical pattern is `window.scrollTo({top, behavior:'smooth'})`
+ * with a pre-computed pixel target — NOT `element.scrollIntoView()`.
+ * Pre-computing the target lets the browser run a clean uninterrupted
+ * smooth animation to a fixed pixel value. `scrollIntoView` re-targets
+ * continuously as the page layout shifts during the animation, which
+ * causes visible jitter when content above the target is also moving
+ * (a sibling collapsing, an async image loading, …).
+ *
+ * The `adjustTargetY` callback is the escape hatch for cases where
+ * the consumer KNOWS about an upcoming layout shift and can compute
+ * the correct FINAL target before the animation starts. Example: in
+ * `HelpCenterCard`, clicking row B while row A above is currently
+ * expanded — A's drawer collapses simultaneously with B's expansion,
+ * shifting B's tile up by A's drawer height. The consumer passes
+ * `adjustTargetY: raw => raw - getAboveDrawerHeight()` and the
+ * browser smooth-scrolls to the post-collapse position directly.
+ */
+
+export interface ScrollElementIntoViewOptions {
+  /** Pixels to subtract from the target element's `top` so it lands
+   *  BELOW sticky chrome. Defaults to 0. Pass `96` (matches
+   *  `scroll-mt-24`) for the standard hub header offset. */
+  headerOffset?: number
+  /** Scroll animation style. Defaults to `'smooth'`. Use `'instant'`
+   *  for imperative jumps where animation would feel laggy (deep
+   *  link land, programmatic focus moves). */
+  behavior?: ScrollBehavior
+  /** Optional adjustment applied to the computed pixel target. The
+   *  callback receives the "raw" Y (`element.top + scrollY -
+   *  headerOffset`) and returns the FINAL pixel target. Use this
+   *  when the caller knows about a layout shift that will happen
+   *  between the call and the animation completing — the browser's
+   *  smooth-scroll commits to a single pixel value, so providing the
+   *  post-shift target up front lands the element correctly even as
+   *  content above it moves. */
+  adjustTargetY?: (rawTargetY: number) => number
+}
+
+/**
+ * Scroll the page so `target` lands at the top of the viewport,
+ * accounting for sticky chrome via `headerOffset`. Returns void; the
+ * scroll runs async via the browser's smooth-scroll engine.
+ *
+ * Accepts:
+ *   - `HTMLElement` — direct reference (most common from `useRef`).
+ *   - `null` / `undefined` — no-op so callers can pass refs without
+ *     defensive branching.
+ *
+ * SSR-safe: short-circuits when `window` is undefined.
+ */
+export function scrollElementIntoView(
+  target: HTMLElement | null | undefined,
+  options: ScrollElementIntoViewOptions = {},
+): void {
+  if (typeof window === 'undefined' || !target) return
+  const { headerOffset = 0, behavior = 'smooth', adjustTargetY } = options
+  const rawTargetY =
+    target.getBoundingClientRect().top + window.scrollY - headerOffset
+  const finalY = adjustTargetY ? adjustTargetY(rawTargetY) : rawTargetY
+  window.scrollTo({ top: Math.max(0, finalY), behavior })
+}