@flamingo-stack/openframe-frontend-core 0.0.773 → 0.0.775

package/src/components/features/video.tsx

@@ -32,6 +32,7 @@
 import type React from 'react';
 import {
   createElement,
+  forwardRef,
   useCallback,
   useEffect,
   useMemo,
@@ -40,10 +41,12 @@ import {
   useSyncExternalStore,
   type ComponentType,
 } from 'react';
+import Image from '../../embed-shims/next-image';
 import { useNearViewport } from '../../hooks/use-near-viewport';
 import { cn } from '../../utils/cn';
 import { fetchPriorityProp } from '../../utils/fetch-priority';
 import { UnifiedSkeleton } from '../loading/unified-skeleton';
+import { Button } from '../ui/button/button';
 import { useLoadingScope } from '../ui/loading-scope';
 import { VideoPlayBadge } from './video-center-badge';
 import type { FilePlayerProps } from './video-file-player';
@@ -97,26 +100,105 @@ function subscribeToFilePlayer(listener: () => void): () => void {
 const loadedFilePlayer = () => filePlayer;
 const noFilePlayer = () => null;
 
-/** The player's box while its module loads: the poster at the player's own size, so nothing moves. */
-function FilePlayerFallback({ poster, className }: { poster?: string | null; className?: string }) {
+/**
+ * The video's box with its poster in it, until the player is drawn. The poster is a real image, not a CSS background:
+ * a background is found only after layout and is never ranked, so on a page whose video is the largest thing painted
+ * the poster arrived last (CU-17tkuw5xp4q). A `priority` video's poster is fetched at once and ranked high.
+ */
+const PosterBox = forwardRef<
+  HTMLDivElement,
+  { poster?: string | null; className?: string; priority?: boolean; fill?: boolean }
+>(function PosterBoxView({ poster, className, priority, fill }, ref) {
   return (
     <div
+      ref={ref}
       aria-hidden="true"
-      className={className}
-      style={{
-        width: '100%',
-        height: '100%',
-        ...(poster ? { backgroundImage: `url(${poster})`, backgroundSize: 'cover', backgroundPosition: 'center' } : {}),
-      }}
-    />
+      className={cn('relative overflow-hidden', className)}
+      style={fill ? { width: '100%', height: '100%' } : undefined}
+    >
+      {poster ? (
+        <Image src={poster} alt="" fill sizes="100vw" priority={priority} unoptimized className="object-cover" />
+      ) : null}
+    </div>
   );
+});
+
+/** The player's box while its module loads: the poster at the player's own size, so nothing moves. */
+function FilePlayerFallback({
+  poster,
+  className,
+  priority,
+}: {
+  poster?: string | null;
+  className?: string;
+  priority?: boolean;
+}) {
+  return <PosterBox poster={poster} className={className} priority={priority} fill />;
 }
 
-function FilePlayer(props: FilePlayerProps): React.ReactElement {
+/**
+ * A video nobody has asked to play yet starts as its poster and a play button, the way a YouTube video does
+ * (`YouTubeFacade`): the player and hls.js are the largest script a page can load, and on a page whose video waits for
+ * a click (a session, an episode, a release) loading them up front cost every visitor a long main-thread task before
+ * anyone pressed play (CU-17tkuw5xp4q). A pointer, focus or touch on the button starts the download, so the player is
+ * usually there by the click, and the click plays it with sound. A video that plays by itself (autoplay, hover
+ * playback, a resumed position, chrome-less) or whose host drives it through a handle mounts its player as before.
+ */
+function waitsForPlay(props: FilePlayerProps): boolean {
+  return (
+    !props.autoPlay &&
+    !props.autoPlayUnmuted &&
+    !props.playOnHover &&
+    props.playWhenHovered === undefined &&
+    props.startTime === undefined &&
+    !props.playerHandleRef &&
+    !props.chromeless
+  );
+}
+
+function FilePlayer({
+  title,
+  priority,
+  ...props
+}: FilePlayerProps & { title?: string; priority?: boolean }): React.ReactElement {
+  // Decided once: a video that started as a facade stays the player once pressed, whatever its props do later.
+  const [facade] = useState(() => waitsForPlay(props));
+  const [pressed, setPressed] = useState(false);
+  if (facade && !pressed) {
+    return (
+      <div className={cn('relative', props.className)} style={{ width: '100%', height: '100%' }}>
+        <FilePlayerFallback poster={props.poster} className="absolute inset-0" priority={priority} />
+        <Button
+          type="button"
+          variant="glyph"
+          size="wrap"
+          aria-label={title ? `Play: ${title}` : 'Play video'}
+          onPointerEnter={loadFilePlayer}
+          onFocus={loadFilePlayer}
+          onTouchStart={loadFilePlayer}
+          onClick={() => {
+            loadFilePlayer();
+            setPressed(true);
+          }}
+          className="group absolute inset-0 rounded-none"
+        >
+          <VideoPlayBadge
+            size="lg"
+            className="transition-transform duration-200 group-hover:scale-110 group-hover:text-ods-accent"
+          />
+        </Button>
+      </div>
+    );
+  }
+  // Pressed: the click is the visitor's gesture, so the player starts with sound (muted if the browser refuses).
+  return <LoadedFilePlayer {...props} priority={priority} {...(facade ? { autoPlayUnmuted: true } : {})} />;
+}
+
+function LoadedFilePlayer({ priority, ...props }: FilePlayerProps & { priority?: boolean }): React.ReactElement {
   // The player's component when its module has arrived (a loaded module, drawn through `createElement`).
   const arrived = useSyncExternalStore(subscribeToFilePlayer, loadedFilePlayer, noFilePlayer);
   if (arrived) return createElement(arrived, props);
-  return <FilePlayerFallback poster={props.poster} className={props.className} />;
+  return <FilePlayerFallback poster={props.poster} className={props.className} priority={priority} />;
 }
 
 // =============================================================================
@@ -207,18 +289,17 @@ export function Video(props: VideoProps): React.ReactElement | null {
 
   const effectiveKind = resolveKind(props, url);
 
-  if (props.lazy && !isNear) {
+  // Drawn when it comes near the screen, like it plays when it is on it: the player and hls.js are the largest
+  // script a page can load, so a video below the fold costs its poster until it is approached. `lazy={false}`
+  // mounts the player at once (a caller that drives playback itself before it is seen).
+  if ((props.lazy ?? true) && !isNear) {
     // Same box, poster only: the observer target IS the reserved space.
     return wrapWithLayout(
-      <div
+      <PosterBox
         ref={nearRef}
+        poster={props.poster}
         className={props.className}
-        style={
-          props.poster
-            ? { backgroundImage: `url(${props.poster})`, backgroundSize: 'cover', backgroundPosition: 'center' }
-            : undefined
-        }
-        aria-hidden="true"
+        priority={'priority' in props ? props.priority : undefined}
       />,
       layout,
     );
@@ -246,6 +327,8 @@ export function Video(props: VideoProps): React.ReactElement | null {
       <FilePlayer
         url={url}
         poster={props.poster}
+        title={props.title}
+        priority={props.priority}
         muted={props.muted}
         {...pickFilePlayback(props)}
         className={props.className}

package/src/components/navigation/mingo-ai-button.tsx

@@ -7,7 +7,7 @@ import { useVisitorOs } from '../../hooks/ui/use-visitor-os';
 import { cn } from '../../utils';
 import { shortcutLabel, usesCommandKey } from '../../utils/visitor-os';
 import { AgentMark } from '../agent-mark';
-import { ASK_AI_OPEN_EVENT } from '../chat/utils/ask-ai-events';
+import { ASK_AI_OPEN_EVENT, ASK_AI_TRIGGER_ATTRIBUTE } from '../chat/utils/ask-ai-events';
 import { Button } from '../ui/button';
 
 export interface MingoAiButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
@@ -132,6 +132,7 @@ export function MingoAiButton({
     <Button
       {...props}
       type="button"
+      {...{ [ASK_AI_TRIGGER_ATTRIBUTE]: '' }}
       variant={field ? 'glyph' : 'transparent'}
       size="wrap"
       font="regular"

package/src/components/navigation/site-header.tsx

@@ -314,7 +314,9 @@ export function SiteHeader({
                 />
               )}
               {nav.signIn && (
-                <div className="hidden lg:flex">
+                // `data-site-signin`: a host whose page is the same for every visitor (served from a CDN) hides it
+                // before paint for a visitor with a session, so a signed-in visitor never sees it flash.
+                <div className="hidden lg:flex" data-site-signin="">
                   <Button
                     asChild
                     variant="transparent"

package/src/components/related-content/card-registry.tsx

@@ -580,6 +580,11 @@ export interface RelatedCardContext {
   anchorAttrs: Pick<CardLinkAnchorProps, 'target' | 'rel'>;
   /** Branded OG fallback for cards whose row has no featured image. */
   placeholderUrl?: string;
+  /**
+   * The rail's first card: its image is likely the page's largest paint (an author page opens on it), so a card that
+   * can rank its image fetches it at once instead of lazily.
+   */
+  priority?: boolean;
   extras?: ChatCardDispatchExtras;
 }
 
@@ -645,6 +650,7 @@ function programEntry(configKey: 'podcast' | 'webinar' | 'event'): RelatedCardRe
           href={ctx.href}
           targetPlatform={ctx.targetPlatform}
           placeholderUrl={ctx.placeholderUrl}
+          priority={ctx.priority}
           {...ctx.anchorAttrs}
         />
       );
@@ -684,6 +690,7 @@ export const RELATED_CARD_REGISTRY: Record<string, RelatedCardRegistryEntry> = {
         href={ctx.href}
         targetPlatform={ctx.targetPlatform}
         placeholderUrl={ctx.placeholderUrl}
+        priority={ctx.priority}
         {...ctx.anchorAttrs}
       />
     ),

package/src/components/related-content/index.ts

@@ -3,10 +3,11 @@ export {
   RelatedContentSection,
   RelatedContentSectionSkeleton,
   type RelatedContentSectionSkeletonProps,
-  GROUP_PAGE_SIZE,
   type RelatedContentSectionProps,
   type CardLinkProvider,
   type CardLinkProviderProps,
   type AdminCampaignCardSlot,
 } from './related-content-section';
 export { type CardLinkAnchorProps } from './card-registry';
+// The page size is server-safe data (utils/content-ref-groups); kept on this subpath for its existing importers.
+export { GROUP_PAGE_SIZE } from '../../utils/content-ref-groups';

package/src/components/related-content/related-content-section.tsx

@@ -54,6 +54,7 @@ import { useSelfFetch } from '../../hooks/use-self-fetch';
 import type { ContentRef, ContentRefWithReason } from '../../types/content-ref';
 import {
   CONTENT_REF_GROUPS,
+  GROUP_PAGE_SIZE,
   getContentRefLabelOrTitleCase,
   orderContentRefTypes,
   type ContentRefGroupConfig,
@@ -199,8 +200,11 @@ function CardForType({
   linkProps,
   extras,
   adminCampaignCard,
+  priority,
 }: {
   type: string;
+  /** The rail's first card: its image is fetched at once (see `RelatedCardContext.priority`). */
+  priority?: boolean;
   /** One fetched row, still unvalidated. Its shape is decided at RUNTIME by
    *  `type` (each group fetches from its own per-type list API), so it stays
    *  `unknown` right up to the registry entry for that type — which owns the
@@ -246,6 +250,7 @@ function CardForType({
     // a numeric title reached `buildOgPlaceholderUrl` as a number. `rowString`
     // makes the claim true.
     placeholderUrl: extras?.buildOgPlaceholderUrl?.(rowString(item, 'title') ?? '') ?? undefined,
+    priority,
     extras,
   });
 }
@@ -259,10 +264,18 @@ function CardForType({
 // refetch, no cross-mount cache.
 // =============================================================================
 
-function useGroupItems(type: string, refs: ContentRef[], buildUrl: (type: string, ids: string[]) => string | null) {
+function useGroupItems(
+  type: string,
+  refs: ContentRef[],
+  buildUrl: (type: string, ids: string[]) => string | null,
+  seedRows?: ReadonlyArray<unknown>,
+) {
   const ids = refs.map(r => r.id);
   const url = ids.length > 0 ? buildUrl(type, ids) : null;
-  const [pages, setPages] = useState<ReadonlyMap<string, unknown[]>>(() => new Map());
+  // The page the server already read (`initialRows`) is in hand from the first render, the server's included.
+  const [pages, setPages] = useState<ReadonlyMap<string, unknown[]>>(() =>
+    seedRows && url !== null ? new Map([[url, [...seedRows]]]) : new Map(),
+  );
   const cached = url !== null ? pages.get(url) : undefined;
   const { data, dataUrl, error } = useSelfFetch<unknown>(cached ? null : url);
   if (data != null && dataUrl !== null && !pages.has(dataUrl)) {
@@ -302,15 +315,8 @@ function resolveGroupConfig(type: string): ContentRefGroupConfig {
   );
 }
 
-/** Items per page within one type group. Groups larger than this paginate
- *  with the standard Pagination control (NO nested scrolling — a bounded
- *  scrollbox inside the page traps wheel events and hides the sections
- *  below it). MUST stay at or above the largest suggestion fill
- *  (RELATED_SAME_TYPE_COUNT in the hub's lib/constants/suggestions.ts) so
- *  current rails never paginate — only genuinely big groups (author pages)
- *  do. Exported through the subpath barrel for the hub's module-load
- *  assertion of that relation (entity-suggestion-sections.tsx). */
-export const GROUP_PAGE_SIZE = 12;
+// The page size (`GROUP_PAGE_SIZE`) lives with the groups' other settings (`utils/content-ref-groups`, server-safe), so
+// a server page can read a group's first page for `initialRows`.
 
 /** A group's layout, read by the group and by the rail's skeleton, so the skeleton is the rail's size. */
 const GROUP_CLASS = 'space-y-4';
@@ -358,9 +364,15 @@ function ContentGroup({
   adminCampaignCard,
   heading,
   onLoadingChange,
+  seedRows,
+  leadsRail = false,
 }: {
   type: string;
   refs: ContentRef[];
+  /** The rows of this group's FIRST page, read by the server (`initialRows`). */
+  seedRows?: ReadonlyArray<unknown>;
+  /** The rail's first group: its first card's image is fetched at once. */
+  leadsRail?: boolean;
   columns: 2 | 3;
   buildUrl: (type: string, ids: string[]) => string | null;
   resolveHref: (ref: ContentRef) => { href: string | null; targetPlatform: string | null };
@@ -392,7 +404,7 @@ function ContentGroup({
   }
   const totalGroupPages = pageCount(refs.length, GROUP_PAGE_SIZE);
   const pageRefs = refs.slice((page - 1) * GROUP_PAGE_SIZE, page * GROUP_PAGE_SIZE);
-  const { items, isLoading } = useGroupItems(type, pageRefs, buildUrl);
+  const { items, isLoading } = useGroupItems(type, pageRefs, buildUrl, seedRows);
   const groupPagination =
     totalGroupPages > 1 ? <Pagination currentPage={page} totalPages={totalGroupPages} onPageChange={setPage} /> : null;
   useEffect(() => {
@@ -443,7 +455,7 @@ function ContentGroup({
   const itemById = new Map(items.map(it => [rowKey(it), it]));
 
   const cards = pageRefs
-    .map(contentRef => {
+    .map((contentRef, index) => {
       const itemId = String(contentRef.id);
       const item = itemById.get(itemId);
       if (!item) return null;
@@ -466,6 +478,8 @@ function ContentGroup({
                 linkProps={linkProps}
                 extras={extras}
                 adminCampaignCard={adminCampaignCard}
+                // The rail's first card, on its first page: the top of the rail, often the page's largest paint.
+                priority={leadsRail && page === 1 && index === 0}
               />
             )}
           </LinkProvider>
@@ -540,6 +554,13 @@ export interface RelatedContentSectionProps {
    *  drills the refs here; the first client fetch is skipped (useSelfFetch
    *  initialData contract). */
   initialItems?: ContentRefWithReason[];
+  /**
+   * The rows of each group's FIRST page, read by the server, keyed by the refs' `type`: exactly what the group's list
+   * URL answers for those ids (`buildListUrl(type, firstPageIds)`). The cards are then in the server HTML instead of
+   * appearing after a request per group in the browser, which on an author page made a card the page's largest paint
+   * seconds after load (CU-17tkuw5xp4q). A group with no entry fetches as before; later pages always fetch.
+   */
+  initialRows?: Readonly<Record<string, ReadonlyArray<unknown>>>;
   /** Section title (default: "Related Content") */
   title?: string;
   /**
@@ -612,6 +633,7 @@ export function RelatedContentSection({
   sameTypeMinResults,
   includeTypes,
   initialItems,
+  initialRows,
   title = 'Related Content',
   columns = 2,
   excludeTypes,
@@ -774,7 +796,7 @@ export function RelatedContentSection({
   return (
     <LoadingRegion as="section" label="Loading related content" announce={loadingTypes.size > 0} className={RAIL_CLASS}>
       <h2 className={RAIL_TITLE_CLASS}>{accentSentenceMarks(title)}</h2>
-      {orderedTypes.map(type => (
+      {orderedTypes.map((type, groupIndex) => (
         <ContentGroup
           key={type}
           type={type}
@@ -787,6 +809,8 @@ export function RelatedContentSection({
           adminCampaignCard={adminCampaignCard}
           heading={<GroupHeading type={type} />}
           onLoadingChange={onGroupLoadingChange}
+          seedRows={initialRows?.[type]}
+          leadsRail={groupIndex === 0}
         />
       ))}
     </LoadingRegion>

package/src/components/ui/photo-wall.tsx

@@ -26,6 +26,13 @@ import { MarqueeWall } from './marquee-wall';
 export interface PhotoWallImage {
   url: string;
   alt?: string;
+  /**
+   * The picture's pixel size, when the host knows it (a server that read the file). A picture with a size is laid
+   * out at once; one without is measured in the browser first, and the wall waits for that, so it is the page's
+   * largest paint only after every picture has loaded (CU-17tkuw5xp4q).
+   */
+  width?: number;
+  height?: number;
 }
 
 export type PhotoOrientation = 'tall' | 'wide' | 'square';
@@ -174,6 +181,14 @@ export interface PhotoWallProps {
   className?: string;
   /** The pictures are still being fetched: show the wall's own placeholder frames. */
   loading?: boolean;
+  /**
+   * The width a column is drawn at, as an image `sizes` value (e.g. `(min-width: 1024px) 25vw, 50vw`). With it, and a
+   * size on every picture, the wall is laid out at once, on the server too, and each picture is drawn with the host's
+   * `srcset`: the first frames are in the HTML and fetched before any script runs, instead of after the wall has been
+   * measured in the browser (CU-17tkuw5xp4q: the careers hero's largest paint waited for that). Two walls given the
+   * same pictures and `sizes` (one per breakpoint) ask for the same files.
+   */
+  sizes?: string;
 }
 
 export function PhotoWall({
@@ -183,6 +198,7 @@ export function PhotoWall({
   fadeColor,
   className,
   loading: loadingProp = false,
+  sizes,
 }: PhotoWallProps) {
   // In a page's loading state the pictures are read: the wall draws its placeholder frames and measures nothing.
   const inScope = useLoadingScope();
@@ -218,18 +234,36 @@ export function PhotoWall({
       : undefined;
   // One frame per picture: a url listed twice is its first entry. Nothing is
   // asked for before the wall knows its width.
+  // Laid out without measuring: every picture's size is stated and the caller states the column's width.
+  const sizedUpFront = !!sizes && images.length > 0 && images.every(image => image.width && image.height);
   const unique = useMemo(() => {
-    if (requestWidth === undefined || inScope) return [];
+    if (inScope || (!sizedUpFront && requestWidth === undefined)) return [];
     const byUrl = new Map<string, PhotoWallImage>();
     for (const image of images) if (!byUrl.has(image.url)) byUrl.set(image.url, image);
     return Array.from(byUrl.values());
-  }, [images, requestWidth, inScope]);
+  }, [images, requestWidth, inScope, sizedUpFront]);
   // Each picture is measured at the url it is drawn from (the boxed `Image`'s
   // `optimizedWidth`: the host's resizer at the column's width), so it is downloaded once.
-  const drawnWidth = requestWidth ?? undefined;
+  // Laid out up front, a picture is drawn from its own url with the host's `srcset` (`sizes`), on the server too.
+  const drawnWidth = sizedUpFront ? undefined : (requestWidth ?? undefined);
   const drawnUrl = useCallback((url: string) => (drawnWidth ? resizedImageUrl(url, drawnWidth) : url), [drawnWidth]);
-  const urls = useMemo(() => unique.map(image => drawnUrl(image.url)), [unique, drawnUrl]);
-  const orientations = usePhotoOrientations(urls);
+  // A picture whose size the host stated has its orientation now; only the others are measured.
+  const known = useMemo(() => {
+    const byUrl = new Map<string, PhotoOrientation>();
+    for (const image of unique) {
+      if (image.width && image.height) byUrl.set(drawnUrl(image.url), photoOrientation(image.width, image.height));
+    }
+    return byUrl;
+  }, [unique, drawnUrl]);
+  const urls = useMemo(
+    () => unique.map(image => drawnUrl(image.url)).filter(url => !known.has(url)),
+    [unique, drawnUrl, known],
+  );
+  const probed = usePhotoOrientations(urls);
+  const orientations = useMemo(() => {
+    if (urls.length === 0) return known;
+    return probed ? new Map([...known, ...probed]) : null;
+  }, [urls, known, probed]);
 
   const layout = useMemo(() => {
     if (!orientations) return null;
@@ -254,7 +288,7 @@ export function PhotoWall({
 
   if (images.length === 0 && !loading) return null;
   // Until the pictures arrive AND their sizes are known, the same placeholder frames.
-  const columnsToDraw = loading || requestWidth === undefined ? null : layout;
+  const columnsToDraw = loading || (!sizedUpFront && requestWidth === undefined) ? null : layout;
 
   const gridStyle = {
     gridTemplateColumns: `repeat(${columnsToDraw?.length || columns}, minmax(0, 1fr))`,
@@ -290,10 +324,9 @@ export function PhotoWall({
                     alt={photo.alt ?? ''}
                     fill
                     className="object-cover"
-                    // Asked for at the column's width. With no step that covers the column the
-                    // caller's url is drawn as it is (already sized by its own image service).
-                    optimizedWidth={drawnWidth}
-                    unoptimized
+                    // Asked for at the column's width: through the host's `srcset` when the wall was laid
+                    // out up front, else at the measured width (the caller's url when no step covers it).
+                    {...(sizedUpFront ? { sizes } : { optimizedWidth: drawnWidth, unoptimized: true })}
                     // A column's first frames are on screen when the wall appears (one of them is
                     // usually the page's largest paint), so they are not left to lazy loading.
                     loading={i < EAGER_PHOTOS_PER_COLUMN ? 'eager' : 'lazy'}

package/src/components/ui/tab-navigation.tsx

@@ -657,7 +657,22 @@ export function TabNavigationSkeleton({
   );
 }
 
-export function TabNavigation({
+/**
+ * Only a URL-synced bar reads the URL. `useSearchParams()` in a component makes Next render the whole page in the
+ * browser when it is prerendered (or fail the build without a Suspense boundary), so a page whose tabs are plain
+ * controlled state (`urlSync` off, the default) must not call it: that is what kept every page with a tab strip
+ * (the flamingo homepage) from being served from a CDN (CU-17tkuw5xp4q). `urlSync` is fixed per bar; switching it
+ * remounts the bar.
+ */
+export function TabNavigation(props: TabNavigationProps) {
+  return props.urlSync ? <UrlSyncedTabNavigation {...props} /> : <TabNavigationBody {...props} searchParams={null} />;
+}
+
+function UrlSyncedTabNavigation(props: TabNavigationProps) {
+  return <TabNavigationBody {...props} searchParams={useSearchParams()} />;
+}
+
+function TabNavigationBody({
   activeTab: controlledActiveTab,
   onTabChange: controlledOnTabChange,
   tabs,
@@ -673,12 +688,12 @@ export function TabNavigation({
   defaultTab,
   staticLabels = false,
   children,
-}: TabNavigationProps) {
+  searchParams,
+}: TabNavigationProps & { searchParams: ReturnType<typeof useSearchParams> | null }) {
   const providedVariant = useContext(TabNavigationVariantContext);
   const variant = variantProp ?? providedVariant;
   const router = useRouter();
   const pathname = usePathname();
-  const searchParams = useSearchParams();
 
   // Determine URL sync settings
   const isUrlSyncEnabled = !!urlSync;

package/src/hooks/use-near-viewport.ts

@@ -126,6 +126,12 @@ export function useNearViewport<T extends Element = HTMLElement>(
 
       elRef.current = node;
       if (!node) return;
+      // No observer (an old browser, a test DOM): draw now. A gate that can never open would hide the content for
+      // good, and every caller's fallback is the content itself.
+      if (typeof IntersectionObserver === 'undefined') {
+        setIsNear(true);
+        return;
+      }
 
       const cb = () => setIsNear(true);
       subscribers.set(node, cb);

package/src/utils/content-ref-groups.ts

@@ -87,3 +87,12 @@ export function orderContentRefTypes(present: Iterable<string>): string[] {
   const unregistered = [...presentSet].filter(type => !CONTENT_REF_GROUPS[type]);
   return [...registeredInOrder, ...unregistered];
 }
+
+/** Items per page within one type group of the related-content rail. Groups larger than this paginate
+ *  with the standard Pagination control (NO nested scrolling — a bounded
+ *  scrollbox inside the page traps wheel events and hides the sections
+ *  below it). MUST stay at or above the largest suggestion fill
+ *  (RELATED_SAME_TYPE_COUNT in the hub's lib/constants/suggestions.ts) so
+ *  current rails never paginate — only genuinely big groups (author pages)
+ *  do. Server-safe here (no client boundary), so a server page can read a group's first page (`initialRows`). */
+export const GROUP_PAGE_SIZE = 12;

package/src/utils/dismiss-cookie.ts

@@ -125,3 +125,20 @@ export function clearDismissCookie(name: string): void {
   fallbackStore(name).clear();
   document.cookie = `${name}=; path=/; max-age=0`;
 }
+
+/**
+ * The inline script that applies a dismissal BEFORE the first paint, for a page
+ * the server renders the same for every visitor (and a CDN may cache), so the
+ * server cannot read the cookie: placed early in `<body>`, it marks the
+ * document root with `attribute` when the cookie holds `id`, and the host's CSS
+ * hides the surface on that attribute. Without it the surface paints and then
+ * collapses once the bundle hydrates: a flash and a layout shift.
+ *
+ * Same match rule as `isDismissedCookieValue` (the id, never mere presence) and
+ * the same encoding `writeDismissCookie` uses. Cookie tier only: a
+ * cookie-averse document (a native shell) is not a cached web page. Any throw
+ * leaves the surface shown, the failing-open side.
+ */
+export function dismissedBeforePaintScript(name: string, id: string, attribute: string): string {
+  return `(function(){try{var n=${JSON.stringify(`${name}=`)},c=document.cookie.split('; ');for(var i=0;i<c.length;i++){if(c[i].indexOf(n)===0&&decodeURIComponent(c[i].slice(n.length))===${JSON.stringify(id)}){document.documentElement.setAttribute(${JSON.stringify(attribute)},'');break}}}catch(e){}})();`;
+}

package/src/utils/index.ts

@@ -383,6 +383,7 @@ export type { FaqHashTarget } from './faq-anchor';
 // pure + server-safe; the hub re-exports these from its config/util shims.
 export {
   CONTENT_REF_GROUPS,
+  GROUP_PAGE_SIZE,
   getContentRefLabel,
   getContentRefLabelOrTitleCase,
   orderContentRefTypes,

package/src/utils/visitor-os.ts

@@ -82,3 +82,15 @@ export function usesCommandKey(os: VisitorOs | null): boolean {
 export function shortcutLabel(os: VisitorOs | null, key: string): string {
   return usesCommandKey(os) ? `⌘${key}` : `Ctrl ${key}`;
 }
+
+/**
+ * The inline script that marks the document with the visitor's DESKTOP system before the first paint
+ * (`attribute` = `mac` | `windows` | `linux`, absent for a phone, a tablet or an unknown system), for a page the
+ * server renders the same for every visitor (and a CDN may cache): it draws every system's variant and the host's
+ * CSS shows the one the attribute names, so the right one is there from the first frame with no hydration
+ * mismatch. The same rule as `detectVisitorOs` (Client Hints platform, then the User-Agent, touch points telling an
+ * iPad from a Mac), held equal to it by the tests. Any throw leaves the attribute off: the host's no-system variant.
+ */
+export function desktopOsBeforePaintScript(attribute: string): string {
+  return `(function(){try{var n=window.navigator,h=n.userAgentData&&n.userAgentData.platform,p=String(h||'').replace(/"/g,'').trim().toLowerCase(),t=(n.maxTouchPoints||0)>1,o=null,m=${JSON.stringify(HINT_PLATFORMS)};if(m[p])o=m[p];else{var u=n.userAgent||'';if(/iPhone|iPad|iPod/i.test(u))o='ios';else if(/Android/i.test(u))o='android';else if(/Windows NT|Win64|Win32/i.test(u))o='windows';else if(/Macintosh|Mac OS X/i.test(u))o='mac';else if(/Linux|X11|CrOS/i.test(u))o='linux'}if(o==='mac'&&t)o='ios';if(o==='mac'||o==='windows'||o==='linux')document.documentElement.setAttribute(${JSON.stringify(attribute)},o)}catch(e){}})();`;
+}