@flamingo-stack/openframe-frontend-core 0.0.292 → 0.0.293

package/dist/utils/same-page-hash-nav.d.ts

@@ -0,0 +1,37 @@
+/** Pages with a section-nav STRIP on top of the global hub header
+ *  (dev-center roadmap/delivery/tickets, FAQ category-pill nav).
+ *  Anchor lands BELOW both layers. */
+export declare const STICKY_HEADER_OFFSET_PX = 96;
+/** Pages with only the global hub header (docs, blog, vendor detail).
+ *  Anchor lands BELOW the header bar. */
+export declare const HUB_HEADER_OFFSET_PX = 80;
+/**
+ * Take only the FIRST hash segment from a fragment that may contain extra
+ * `#` characters. `'' → ''`, `'#a' → '#a'`, `'#a#b' → '#a'`.
+ *
+ * No real DOM id contains `#`, so a multi-fragment hash is always a bug at
+ * the composer site; `navigateSamePageHash` + `useScrollToHash` both call
+ * this so URL bar and `getElementById` stay in sync.
+ */
+export declare function normalizeHashFragment(hash: string): string;
+export interface NavigateSamePageHashOptions {
+    /** Pixels to subtract for sticky chrome. */
+    headerOffset?: number;
+    /** `'push'` (default) — new history entry; `'replace'` — overwrite
+     *  current entry (use for TOC-style in-page navigators). */
+    history?: 'push' | 'replace';
+}
+/**
+ * Same-page hash navigation primitive: pushState + synthetic `hashchange`
+ * + anchoring-proof smooth scroll. Replaces `router.push` for hash CTAs
+ * (Next.js suppresses smooth-scroll during navigation; `router.push` on
+ * an exact-URL match is a no-op). Returns `true` when the helper claimed
+ * the nav (same pathname + search); `false` for cross-page targets so
+ * callers fall through to `router.push`.
+ *
+ * `target` accepts an origin-stripped path (`/x#anchor`) or a bare hash
+ * (`#anchor`); bare-hash callers don't need to reconstruct `pathname +
+ * search` themselves.
+ */
+export declare function navigateSamePageHash(target: string, options?: NavigateSamePageHashOptions): boolean;
+//# sourceMappingURL=same-page-hash-nav.d.ts.map

package/dist/utils/same-page-hash-nav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"same-page-hash-nav.d.ts","sourceRoot":"","sources":["../../src/utils/same-page-hash-nav.ts"],"names":[],"mappings":"AAEA;;sCAEsC;AACtC,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC;yCACyC;AACzC,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED,MAAM,WAAW,2BAA2B;IAC1C,4CAA4C;IAC5C,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;gEAC4D;IAC5D,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAkET"}

package/dist/utils/source-icons.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-icons.d.ts","sourceRoot":"","sources":["../../src/utils/source-icons.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA2CpD,CAAA;AAED;;6DAE6D;AAC7D,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGxF;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA2CzD,CAAA;AAED;;kEAEkE;AAClE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iCAAiC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA2CpE,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEjF"}
+{"version":3,"file":"source-icons.d.ts","sourceRoot":"","sources":["../../src/utils/source-icons.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA2CpD,CAAA;AAED;;6DAE6D;AAC7D,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGxF;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiDzD,CAAA;AAED;;kEAEkE;AAClE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iCAAiC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA2CpE,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEjF"}

package/package.json

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

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

@@ -100,6 +100,12 @@ export interface RoadmapCardProps {
   cardType?: 'roadmap_item' | 'delivery_item' | 'internal_task'
   size?: CardSize
   className?: string
+  /** DOM `id` applied to the card's outer element. `RoadmapGrid` sets
+   *  `roadmap-<external_id>` so chat-card deep-links
+   *  (`?search=<id>#roadmap-<id>`) have a target for `useScrollToHash`
+   *  to scroll to. `scroll-mt-24` on the outer element keeps the card
+   *  BELOW the sticky chrome. */
+  id?: string
   // Default-branch vote controls (ignored in `sm`):
   userVote?: VoteType | null
   onVote?: (voteType: 'up' | 'down') => void
@@ -116,6 +122,7 @@ export function RoadmapCard({
   size = 'default',
   cardType = 'roadmap_item',
   className,
+  id,
   userVote,
   onVote,
   isVoting = false,
@@ -233,7 +240,7 @@ export function RoadmapCard({
   }
 
   return (
-    <div className={`bg-ods-card border border-ods-border rounded-[6px] p-[24px] flex flex-col gap-[16px] hover:border-ods-accent transition-all h-full ${className ?? ''}`}>
+    <div id={id} className={`bg-ods-card border border-ods-border rounded-[6px] p-[24px] flex flex-col gap-[16px] hover:border-ods-accent transition-all h-full scroll-mt-24 ${className ?? ''}`}>
       <div className="flex gap-[16px] items-center w-full">
         <div className="w-16 h-16 rounded-lg flex items-center justify-center flex-shrink-0 bg-ods-bg border border-ods-border">
           {iconSrc ? (

package/src/components/docs/use-document-tree.ts

@@ -10,11 +10,12 @@ import {
 } from '../../utils/doc-tree-nav'
 import { useDocNavigation } from './doc-navigation-context'
 import { scrollElementIntoView } from '../../utils/scroll-into-view'
+import { navigateSamePageHash, HUB_HEADER_OFFSET_PX } from '../../utils/same-page-hash-nav'
 
 function scrollToContent() {
   const article = document.querySelector('article') as HTMLElement | null
   if (article) {
-    scrollElementIntoView(article, { headerOffset: 80 })
+    scrollElementIntoView(article, { headerOffset: HUB_HEADER_OFFSET_PX })
   } else {
     window.scrollTo({ top: 0, behavior: 'smooth' })
   }
@@ -329,12 +330,52 @@ export function useDocumentTree(
     const anchor = hashIndex !== -1 ? path.substring(hashIndex) : ''
     const cleanPath = path.replace(/\/$/, '').split('#')[0]
 
+    // Same-doc-different-anchor shortcut. Content is already mounted, so we
+    // don't need the 300ms "wait-for-fetch" bandaid — the canonical helper
+    // owns pushState + synthetic `hashchange` (so any in-doc TOC / accordion
+    // bound to the URL hash re-renders) + the anchoring-proof tween in one
+    // sync call. `headerOffset: HUB_HEADER_OFFSET_PX` matches the cross-doc path below so
+    // anchors land BELOW the docs sticky header on every same-doc internal
+    // link click. Cross-doc nav (different cleanPath) falls through to the
+    // existing fetch-then-scroll path below.
+    //
+    // We pass the BARE-hash form to the helper rather than reconstructing
+    // a full `${normalizedBaseRoute}/${cleanPath}${anchor}` path: the
+    // helper's pathname check compares against `window.location.pathname`,
+    // which carries the FOLDER-INDEX-STRIPPED form (`/docs/foo` for
+    // `foo/README.md`, `/docs` for the root index). Handing it `cleanPath`
+    // — the raw resolved path — produces e.g. `/docs/foo/README.md` and
+    // the compare fails → helper returns false → silent dead-click. The
+    // bare-hash form sidesteps that entirely: the helper reconstructs
+    // `pathname + search + hash` from `window.location`, so the compare
+    // is trivially equal. Covers bare `#anchor` links (resolve to
+    // `cleanPath=''`) AND folder-index links (`foo/README.md` resolving
+    // to the current `/docs/foo`).
+    // Bare-hash internal links (`[Click](#section)`) come in as
+    // `path === '#section'`, so `cleanPath` becomes `''` and the naive
+    // strip-then-compare misses the same-doc shortcut on every NON-root
+    // doc (selectedPath is e.g. `'foo/bar'`, not `''`). For that case the
+    // current doc IS the same-doc target by definition — short-circuit
+    // pathForSelection to the current selection so the shortcut fires.
+    const pathForSelection =
+      anchor && options?.fromInternalLink && cleanPath === ''
+        ? selectedPathRef.current
+        : stripFolderIndexFromPath(cleanPath, folderIndexFile)
+    if (
+      anchor &&
+      options?.fromInternalLink &&
+      pathForSelection === selectedPathRef.current
+    ) {
+      navigateSamePageHash(anchor, { headerOffset: HUB_HEADER_OFFSET_PX })
+      return
+    }
+
     const scrollAfterNav = () => {
       if (anchor) {
         setTimeout(() => {
           const el = document.getElementById(anchor.substring(1))
           if (el) {
-            scrollElementIntoView(el, { headerOffset: 80 })
+            scrollElementIntoView(el, { headerOffset: HUB_HEADER_OFFSET_PX })
           } else {
             scrollToContent()
           }
@@ -370,7 +411,8 @@ export function useDocumentTree(
       return
     }
 
-    const pathForSelection = stripFolderIndexFromPath(cleanPath, folderIndexFile)
+    // `pathForSelection` was already computed above (inside the
+    // same-doc-anchor shortcut check); reuse it here for cross-doc nav.
     const urlPath = pathForSelection
 
     lastFetchedPath.current = null

package/src/components/faq/faq-section.tsx

@@ -7,6 +7,7 @@ import { useSelfFetch } from '../../hooks/use-self-fetch'
 import { buildSuggestionUrl } from '../../utils/suggestion-url'
 import { serializeJsonLd } from '../../utils/common'
 import { scrollElementIntoView } from '../../utils/scroll-into-view'
+import { navigateSamePageHash, STICKY_HEADER_OFFSET_PX } from '../../utils/same-page-hash-nav'
 import { faqSectionSlug, faqItemAnchor, parseFaqHash, type FaqHashTarget } from '../../utils/faq-anchor'
 import { cn } from '../../utils/cn'
 import { buildFaqJsonLdFromFaqs, type FaqSchemaOptions } from './json-ld'
@@ -97,9 +98,6 @@ function groupFaqsBySection(faqs: Faq[]): FaqGroup[] {
   return groups
 }
 
-/** The standard hub sticky-header height — same offset `useNavLink`'s hash
- *  scroll uses, so a category jump lands below the header, not under it. */
-const FAQ_NAV_HEADER_OFFSET = 96
 
 /** Map key for the uncategorized bucket — `group.slug` is null for it, so
  *  every per-group map (default-open ids, accordion keys) uses this sentinel
@@ -160,7 +158,7 @@ function GroupedFaqList({
         }
         if (bestId) setActiveSlug(bestId)
       },
-      { rootMargin: `-${FAQ_NAV_HEADER_OFFSET}px 0px -55% 0px`, threshold: 0 },
+      { rootMargin: `-${STICKY_HEADER_OFFSET_PX}px 0px -55% 0px`, threshold: 0 },
     )
     for (const group of navGroups) {
       const el = group.slug ? document.getElementById(group.slug) : null
@@ -215,18 +213,33 @@ function GroupedFaqList({
     const elId =
       hashTarget.kind === 'item' ? faqItemAnchor(hashTarget.rawId) : hashTarget.slug
     const el = document.getElementById(elId)
-    if (el) scrollElementIntoView(el, { headerOffset: FAQ_NAV_HEADER_OFFSET })
+    if (el) scrollElementIntoView(el, { headerOffset: STICKY_HEADER_OFFSET_PX })
     if (hashTarget.kind === 'section') setActiveSlug(hashTarget.slug)
   }, [hashTarget])
 
+  // Category pill click. `navigateSamePageHash` owns the entire transition:
+  // replaceState → synthetic `hashchange` → `scrollElementIntoView` tween
+  // with `STICKY_HEADER_OFFSET_PX` so the section heading lands BELOW the
+  // sticky category nav on the FIRST tween (covers the same-target
+  // re-click case, where the `hashTarget` effect at L214 is a no-op
+  // because the state reference is equal). For DIFFERENT-target clicks
+  // the helper's synthetic `hashchange` re-fires that effect, which
+  // re-scrolls with the same offset and cancels this tween (singleton)
+  // — both paths land at the same position. The effect is still
+  // required for back/forward + direct URL edits, where the helper
+  // isn't in the call chain.
+  //
+  // `history: 'replace'` matches the pre-helper behavior: category pills
+  // are a TOC, not a navigation step, so the Back button leaves the
+  // FAQ page in one step regardless of how many categories the user
+  // clicked through.
   const handleJump = useCallback(
     (e: React.MouseEvent<HTMLAnchorElement>, slug: string) => {
       e.preventDefault()
-      setActiveSlug(slug)
-      scrollElementIntoView(document.getElementById(slug), {
-        headerOffset: FAQ_NAV_HEADER_OFFSET,
+      navigateSamePageHash('#' + slug, {
+        headerOffset: STICKY_HEADER_OFFSET_PX,
+        history: 'replace',
       })
-      if (typeof history !== 'undefined') history.replaceState(null, '', `#${slug}`)
     },
     [],
   )

package/src/components/shared/delivery/delivery-lists.tsx

@@ -35,7 +35,9 @@ import { DeliveryTable } from './delivery-table';
 import { EmptyState } from '../../empty-state';
 import { LoadError } from '../../ui/error-state';
 import { DEV_SECTION_PARAM_KEYS } from '../../../utils/dev-sections/dev-section-param-keys';
+import { STICKY_HEADER_OFFSET_PX } from '../../../utils/same-page-hash-nav';
 import { contentFetch } from '../../../utils/embed-content-fetch';
+import { useScrollToHash } from '../../../hooks/use-scroll-to-hash';
 
 const DEFAULT_COMPLETED_ENDPOINT = '/api/delivery/completed';
 const DEFAULT_IN_PROGRESS_ENDPOINT = '/api/delivery/in-progress';
@@ -129,6 +131,13 @@ export function DeliveryLists({
   const filteredCompleted = data?.completed || [];
   const filteredInProgress = data?.inProgress || [];
 
+  // Deep-link hash dispatch — `?search=<id>#delivery-<id>` from a chat
+  // card or a linked-delivery card on a ticket. Shared hook owns the
+  // poll-until-mount + hashchange-listener wiring (same instance used
+  // by RoadmapView). 96 matches the sticky-header offset every
+  // hash-scroll surface in the app uses.
+  useScrollToHash(data, { headerOffset: STICKY_HEADER_OFFSET_PX });
+
   const showCompleted = true;
   const showInProgress = true;
 

package/src/components/shared/delivery/delivery-row.tsx

@@ -60,6 +60,13 @@ export interface DeliveryRowProps {
   /** Small uppercase caption rendered above the title. Used by the
    *  linked-delivery card variant ("LINKED DELIVERY"). */
   caption?: string
+  /** DOM `id` applied to the row's outer element. `DeliveryTable`
+   *  always sets `delivery-<external_id>` so chat-card deep-links
+   *  (`?search=<id>#delivery-<id>`) and the ticket linked-card path
+   *  both have a target for `useScrollToHash` to scroll to. Always
+   *  paired with `scroll-mt-24` on the outer element so the row lands
+   *  BELOW the sticky chrome after the scroll. */
+  id?: string
   className?: string
 }
 
@@ -67,6 +74,7 @@ export function DeliveryRow({
   item,
   href,
   caption,
+  id,
   className,
 }: DeliveryRowProps) {
   const taskType = item.taskType as keyof typeof TASK_TYPE_LABELS
@@ -121,6 +129,11 @@ export function DeliveryRow({
 
   const baseClass = cn(
     'block p-[12px] md:p-[16px] no-underline text-inherit transition-colors duration-150',
+    // `scroll-mt-24` is paid for whether `id` is set or not (it's a
+    // single Tailwind utility, no runtime cost). Keeping it
+    // unconditional means a future caller adding `id` doesn't also
+    // have to remember to ask for the offset.
+    'scroll-mt-24',
     href && 'hover:bg-ods-bg-hover cursor-pointer',
     className,
   )
@@ -133,11 +146,11 @@ export function DeliveryRow({
     // losing TanStack-Query state on back, leaving /tickets stuck on
     // its skeleton.
     return (
-      <Link href={href} className={baseClass} prefetch={false}>
+      <Link href={href} id={id} className={baseClass} prefetch={false}>
         {inner}
       </Link>
     )
   }
 
-  return <div className={baseClass}>{inner}</div>
+  return <div id={id} className={baseClass}>{inner}</div>
 }

package/src/components/shared/delivery/delivery-table.tsx

@@ -19,6 +19,7 @@
 
 import { DeliveryRow } from './delivery-row';
 import type { DeliveryItem } from '../../../types/delivery';
+import { devSectionAnchorId } from '../../../utils/dev-sections/dev-section-param-keys';
 
 interface DeliveryTableProps {
   items: DeliveryItem[];
@@ -95,11 +96,16 @@ export function DeliveryTable({ items, isLoading = false }: DeliveryTableProps)
     <div className="bg-ods-card border border-ods-border rounded-[6px] overflow-hidden w-full">
       <div className="w-full">
         {items.map((item) => (
+          // DOM id lives on DeliveryRow's own outer element (no wrapper
+          // div). Anchor mirrors `buildDevSectionUrl('delivery', <id>)`
+          // → `#delivery-<external_id>`; `useScrollToHash` in
+          // `delivery-lists.tsx` finds the row by id and scrolls. The
+          // outer wrapper here ONLY exists for the row separators.
           <div
             key={item.id}
             className="border-b border-ods-border last:border-b-0"
           >
-            <DeliveryRow item={item} />
+            <DeliveryRow item={item} id={devSectionAnchorId('delivery', item.id)} />
           </div>
         ))}
       </div>

package/src/components/shared/roadmap/roadmap-grid.tsx

@@ -33,6 +33,7 @@ import {
   AccordionContent,
 } from '../../ui';
 import { cn } from '../../../utils/cn';
+import { devSectionAnchorId } from '../../../utils/dev-sections/dev-section-param-keys';
 import { contentFetch } from '../../../utils/embed-content-fetch';
 import type { RoadmapItem } from '../../chat/types/entities/roadmap-item';
 
@@ -134,9 +135,15 @@ function RoadmapGridSingle({
   return (
     <div className={`grid grid-cols-1 md:grid-cols-2 gap-6 ${showLeftMargin ? 'md:ml-[120px]' : ''}`}>
       {items.map((item) => (
+        // DOM id + sticky-header scroll offset live ON RoadmapCard's own
+        // outer element (no wrapper div). Anchor mirrors
+        // `buildDevSectionUrl('roadmap', <id>)` → `#roadmap-<external_id>`;
+        // `useScrollToHash` in `roadmap-view.tsx` finds the card by id
+        // and scrolls.
         <RoadmapCard
           key={item.id}
           item={item}
+          id={devSectionAnchorId('roadmap', item.id)}
           userVote={getVote(item.id)}
           onVote={(voteType) => onVote(item.id, voteType)}
           isVoting={votingTasks.has(item.id)}

package/src/components/shared/roadmap/roadmap-view.tsx

@@ -15,11 +15,13 @@ import { useMemo } from 'react'
 import { useSearchParams } from '../../../embed-shims'
 import { LoadError } from '../../ui/error-state'
 import { useSelfFetch } from '../../../hooks/use-self-fetch'
+import { useScrollToHash } from '../../../hooks/use-scroll-to-hash'
 import type { RoadmapItem } from '../../chat/types/entities/roadmap-item'
 import { RoadmapGrid } from './roadmap-grid'
 import { RoadmapGridSkeleton } from './roadmap-grid-skeleton'
 import type { UseRoadmapVotingOptions } from './use-roadmap-voting'
 import { DEV_SECTION_PARAM_KEYS } from '../../../utils/dev-sections/dev-section-param-keys'
+import { STICKY_HEADER_OFFSET_PX } from '../../../utils/same-page-hash-nav'
 
 const DEFAULT_ENDPOINT = '/api/roadmap'
 // Defaults sourced from the ONE param-key registry the chrome (OPENFRAME_DEV_SECTIONS) also
@@ -77,6 +79,15 @@ export function RoadmapView({
   )
   const items = data?.items ?? []
 
+  // Deep-link hash dispatch — `?search=<id>#roadmap-<id>` from a chat card.
+  // Shared hook owns the poll-until-mount + hashchange-listener wiring
+  // (same instance used by DeliveryLists). The rAF poll inside the hook
+  // handles the Radix `<AccordionItem>` lazy-unmount: on first paint
+  // every quarter is collapsed; an effect in `roadmap-grid.tsx` expands
+  // them when `hasActiveFilters` is true (chat URL carries `?search=<id>`).
+  // The card mounts one tick after `data` lands; the hook waits.
+  useScrollToHash(data, { headerOffset: STICKY_HEADER_OFFSET_PX })
+
   if (error) {
     return <LoadError message="Failed to load roadmap." onRetry={reload} />
   }

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

@@ -19,6 +19,7 @@ import { useCallback, useEffect, useRef } from 'react'
 import { StatusBadge, type StatusBadgeProps } from '../ui'
 import { formatRelativeTime } from '../../utils/date-utils'
 import { scrollElementIntoView } from '../../utils/scroll-into-view'
+import { STICKY_HEADER_OFFSET_PX } from '../../utils/same-page-hash-nav'
 import { getStatusColorScheme } from '../chat/utils/agent-status-message'
 import { DevCardRowContent } from '../shared/dev-section/dev-card-row'
 import {
@@ -28,23 +29,6 @@ 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
@@ -59,6 +43,12 @@ export interface HelpCenterCardProps {
    *  (`HelpCenterList`) reads via `actions.replyErrorFor(external_id)`. */
   replyError?: TicketDetailDrawerProps['replyError']
   onClearReplyError?: TicketDetailDrawerProps['onClearReplyError']
+  /** DOM `id` applied to the row's outer element. Parent (`HelpCenterList`)
+   *  sets `ticket-<external_id>` so `useScrollToHash` can deep-link from
+   *  a chat card's `?ticket=<id>#ticket-<id>` URL. The sticky-header
+   *  offset is already baked in via `STICKY_HEADER_OFFSET_PX` so the row
+   *  lands BELOW the chrome regardless of whether `id` is set. */
+  id?: string
 }
 
 export function HelpCenterCard({
@@ -73,6 +63,7 @@ export function HelpCenterCard({
   onActionCollapsed,
   replyError,
   onClearReplyError,
+  id,
 }: HelpCenterCardProps) {
   const optimistic = isOptimistic(ticket)
   const rawStatus = (ticket.status ?? 'OPEN').toUpperCase()
@@ -149,6 +140,7 @@ export function HelpCenterCard({
   return (
     <div
       ref={rowRef}
+      id={id}
       style={{ scrollMarginTop: STICKY_HEADER_OFFSET_PX }}
       className={`border-b border-ods-border last:border-b-0 ${optimistic ? 'opacity-60' : ''}`}
       aria-busy={optimistic || undefined}

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

@@ -35,6 +35,9 @@ import { DevSectionPage } from '../shared/dev-section'
 import { DevCardRowSkeletonList } from '../shared/dev-section/dev-card-row'
 import { UnifiedPagination } from '../unified-pagination'
 import { useChatIdentity } from '../chat/hooks/use-chat-identity'
+import { useScrollToHash } from '../../hooks/use-scroll-to-hash'
+import { STICKY_HEADER_OFFSET_PX } from '../../utils/same-page-hash-nav'
+import { devSectionAnchorId } from '../../utils/dev-sections/dev-section-param-keys'
 import { toast as defaultToast } from '../../hooks/use-toast'
 import { useTicketsList } from './hooks/use-tickets-list'
 import { useTicketActions } from './hooks/use-ticket-actions'
@@ -264,6 +267,15 @@ function HelpCenterListAuthed({
   )
 
   const merged: AnyTicket[] = [...optimisticTickets, ...tickets]
+
+  // Deep-link hash dispatch — `/tickets#ticket-<external_id>` from a
+  // chat card (or any other in-app link). The `?ticket=<external_id>`
+  // query param keeps owning drawer auto-open; this hook owns the
+  // scroll-to-row independently. Both can fire on the same URL
+  // (`/tickets?ticket=X#ticket-X`) — drawer opens AND row scrolls into
+  // view. Shared `useScrollToHash` polls until the row mounts (handles
+  // the SWR fetch race), uses the canonical `scrollElementIntoView` tween.
+  useScrollToHash(tickets, { headerOffset: STICKY_HEADER_OFFSET_PX })
   const hasActiveFilters = search !== '' || (status !== '' && status !== 'all')
   const hasResults = merged.length > 0
 
@@ -343,6 +355,7 @@ function HelpCenterListAuthed({
               {merged.map((ticket) => (
                 <HelpCenterCard
                   key={ticket.id}
+                  id={devSectionAnchorId('ticket', ticket.external_id)}
                   ticket={ticket}
                   expanded={expandedTicketId === ticket.id}
                   onToggle={toggleRow}

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

@@ -25,6 +25,7 @@ import { RefreshCw } from 'lucide-react'
 import { useChatIdentity } from '../chat/hooks/use-chat-identity'
 import { toast as defaultToast } from '../../hooks/use-toast'
 import { formatRelativeTime } from '../../utils/date-utils'
+import { devSectionAnchorId } from '../../utils/dev-sections/dev-section-param-keys'
 import { TicketOpenForm } from './ticket-open-form'
 import { TicketRow } from './ticket-row'
 import { useTicketsList } from './hooks/use-tickets-list'
@@ -168,6 +169,7 @@ function TicketCenterAuthed({
             {merged.map((ticket) => (
               <TicketRow
                 key={ticket.id}
+                id={devSectionAnchorId('ticket', ticket.external_id)}
                 ticket={ticket}
                 expanded={expandedTicketId === ticket.id}
                 onToggle={toggleRow}

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

@@ -48,6 +48,11 @@ export interface TicketRowProps {
   /** Called after a successful close/reopen so the parent can collapse
    *  the drawer (status flipped — current action set is now stale). */
   onActionCollapsed: TicketDetailDrawerProps['onActionCollapsed']
+  /** DOM `id` applied to the row's outer element. Parents that surface
+   *  a deep-link target set `ticket-<external_id>` so `useScrollToHash`
+   *  resolves it. `scroll-mt-24` is already baked into the outer
+   *  element regardless. */
+  id?: string
 }
 
 export function TicketRow({
@@ -60,6 +65,7 @@ export function TicketRow({
   onClose,
   onReopen,
   onActionCollapsed,
+  id,
 }: TicketRowProps) {
   // Optimistic placeholders have no drawer — the real id hasn't
   // arrived yet, so action targets would be undefined.
@@ -123,7 +129,7 @@ export function TicketRow({
   }
 
   return (
-    <div ref={rowRef} className="scroll-mt-24">
+    <div ref={rowRef} id={id} className="scroll-mt-24">
       <Collapsible
         open={expanded && !optimistic}
         className="border-b border-ods-border last:border-b-0"

package/src/hooks/index.ts

@@ -28,6 +28,11 @@ export * from './use-access-code-integration'
 // OG placeholder URL builder hook (requires host-supplied URL builder)
 export * from './use-og-placeholder'
 
+// Deep-link "scroll to URL hash" after data loads. Pairs with URL
+// composers that emit `?<filter>=<id>#<prefix>-<id>` — the filter
+// narrows the list, the hash scrolls the matching DOM id.
+export * from './use-scroll-to-hash'
+
 // Invisible bot-protection client primitive (honeypot ref + submit-timing).
 // Pairs with the server-safe decision fn in `utils/humanity-signals`.
 export * from './use-humanity-signals'

package/src/hooks/use-scroll-to-hash.ts

@@ -0,0 +1,74 @@
+'use client'
+
+import { useEffect } from 'react'
+import { scrollElementIntoView } from '../utils/scroll-into-view'
+import { normalizeHashFragment } from '../utils/same-page-hash-nav'
+
+/** ~1s at 60fps — long enough to outlast Radix accordion expand + SWR
+ *  mount, short enough that a missed anchor doesn't hang the page. */
+const MAX_POLL_FRAMES = 60
+
+export interface UseScrollToHashOptions {
+  /** Pixels to subtract for sticky chrome. */
+  headerOffset?: number
+}
+
+/**
+ * Scroll the page to `window.location.hash` once `readyDep` resolves
+ * to a truthy value. Polls via rAF for ~1s so lazy-mounted rows (Radix
+ * accordion, SWR fetch) have time to render. Re-runs on `readyDep`
+ * reference change AND on `hashchange` (browser back/forward + the
+ * synthetic event `navigateSamePageHash` dispatches).
+ *
+ * Skipped when `readyDep == null || readyDep === false`. Default
+ * `true` makes the hook run on mount for pages whose target is in the
+ * initial SSR render.
+ */
+export function useScrollToHash(
+  readyDep: unknown = true,
+  options?: UseScrollToHashOptions,
+): void {
+  const headerOffset = options?.headerOffset ?? 0
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    if (readyDep === null || readyDep === false) return
+    let rafId: number | null = null
+    const cancelPoll = () => {
+      if (rafId !== null) {
+        cancelAnimationFrame(rafId)
+        rafId = null
+      }
+    }
+    const tryScrollToHash = () => {
+      // `normalizeHashFragment` heals a malformed multi-fragment hash
+      // so `getElementById` resolves on deep-link entries that bypass
+      // `navigateSamePageHash`'s own normalize.
+      const hash = normalizeHashFragment(window.location.hash).slice(1)
+      if (!hash) return
+      // Cancel any in-flight poll from a prior invocation so two
+      // concurrent ticks can't both call scrollElementIntoView.
+      cancelPoll()
+      let frames = 0
+      const tick = () => {
+        const el = document.getElementById(hash)
+        if (el) {
+          rafId = null
+          scrollElementIntoView(el, { headerOffset })
+          return
+        }
+        if (frames++ < MAX_POLL_FRAMES) {
+          rafId = requestAnimationFrame(tick)
+        } else {
+          rafId = null
+        }
+      }
+      tick()
+    }
+    tryScrollToHash()
+    window.addEventListener('hashchange', tryScrollToHash)
+    return () => {
+      window.removeEventListener('hashchange', tryScrollToHash)
+      cancelPoll()
+    }
+  }, [readyDep, headerOffset])
+}

package/src/utils/.source-icons.md

@@ -27,7 +27,7 @@ const iconName = getSourceIconName('github-commits')
 
 // Get display label for a chip strip
 const label = getSourceLabel('hubspot-tickets-anon')
-// → 'Known Issues'
+// → 'Tickets'
 
 // Map a documentType emitted by the LLM to its table ID
 const tableId = defaultTableIdForDocumentType('slack_message')

package/src/utils/dev-sections/dev-section-param-keys.ts

@@ -19,3 +19,17 @@ export const DEV_SECTION_PARAM_KEYS = {
   /** Delivery (bug-fix / enhancement) task-type filter. */
   deliveryTaskType: 'task_type',
 } as const
+
+/** Section keys that participate in `<section>-<id>` anchor IDs.
+ *  The URL composer (`appendSearchAndHash` in hub `dev-section-url.ts`)
+ *  and the row components (`DeliveryRow`, `RoadmapCard`, `HelpCenterCard`)
+ *  both call `devSectionAnchorId` so the DOM `id` and the URL hash stay
+ *  in lockstep — adding a new section means adding the literal here
+ *  ONCE, not at every render site. */
+export type DevSectionAnchorKind = 'roadmap' | 'delivery' | 'ticket'
+
+/** Compose the canonical `<section>-<id>` anchor id used by the dev-center
+ *  rows + URL composer. */
+export function devSectionAnchorId(section: DevSectionAnchorKind, id: string): string {
+  return `${section}-${id}`
+}