@flamingo-stack/openframe-frontend-core 0.0.738 → 0.0.740

package/dist/utils/legal-documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legal-documents.d.ts","sourceRoot":"","sources":["../../src/utils/legal-documents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,iEAAkE,CAAC;AAEpG,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,mFAAmF;AACnF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,iBAAiB,CAE7E"}

package/dist/utils/legal-documents.js

@@ -0,0 +1,8 @@
+const LEGAL_DOCUMENT_TYPES = ["privacy", "terms", "payment", "license", "security"];
+function isLegalDocumentType(value) {
+  return LEGAL_DOCUMENT_TYPES.includes(value);
+}
+export {
+  LEGAL_DOCUMENT_TYPES,
+  isLegalDocumentType
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.738",
+  "version": "0.0.740",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "sideEffects": [

package/src/components/features/walkthrough-video.tsx

@@ -106,6 +106,13 @@ export interface WalkthroughVideoData {
   position?: 'left' | 'right' | null;
 }
 
+/**
+ * What ends Largest Contentful Paint: the browser reports no new candidate after
+ * the visitor's first scroll, tap or key press. The floating card renders only
+ * after one of these.
+ */
+const FIRST_INTERACTION_EVENTS = ['scroll', 'pointerdown', 'keydown'] as const;
+
 /** Everything the two placements share — the widget's actual contract. */
 interface WalkthroughVideoBaseProps {
   video: WalkthroughVideoData | null | undefined;
@@ -148,6 +155,9 @@ interface WalkthroughVideoBaseProps {
  * not in the base.
  */
 export interface FloatingWalkthroughVideoProps extends WalkthroughVideoBaseProps {
+  /** The card appears no sooner than this after load, and only once the visitor
+   *  has scrolled, tapped or pressed a key (so it can never be the page's
+   *  Largest Contentful Paint). Default 3000. */
   appearDelayMs?: number;
   /** Cookie-based dismissal (id-match, mirrors the announcement bar). `false`
    *  disables the X entirely. `storageKey` is the per-platform cookie name. */
@@ -208,9 +218,10 @@ function WalkthroughVideo({
   autoPlayCard = false,
   label = 'Play Demo Video',
   placement,
-  // Keeps the FLOATING card off the critical path. The inline preset passes 0:
-  // an in-page block is part of a page the visitor is already looking at, so
-  // staggering it in would only jump the layout.
+  // The FLOATING card never appears sooner than this (and never before the
+  // visitor's first interaction: see the mount gate). The inline preset passes
+  // 0: an in-page block is part of a page the visitor is already looking at,
+  // so staggering it in would only jump the layout.
   appearDelayMs = 3000,
   dismissal = {},
   hideNearSelector = 'footer',
@@ -224,7 +235,16 @@ function WalkthroughVideo({
   // (embedder) → a stable presence marker so dismissal still works.
   const dismissalId = video?.id != null ? String(video.id) : 'dismissed';
 
-  // --- mount gate (never LCP; cookie read happens post-delay, no hydration mismatch) ---
+  // --- mount gate (cookie read happens post-delay, no hydration mismatch) ---
+  // The FLOATING card waits for two things: the appear delay AND the visitor's
+  // first scroll, tap or key press. The delay alone never kept it out of Largest
+  // Contentful Paint: the metric takes candidates until the first interaction,
+  // so a late card that was the largest thing in a short window became the
+  // page's LCP (blog post, 1440x215: the heading at 3.2 s, then the card's
+  // poster at 7.1 s). No attribute opts an element out, and a timer does not
+  // either; rendering only after the first interaction is the documented way,
+  // because the metric is final by then. The inline block is part of the page's
+  // own content and waits for neither.
   const [mounted, setMounted] = useState(false);
   const [dismissed, setDismissed] = useState(false);
   const hasVideo = video != null;
@@ -235,31 +255,52 @@ function WalkthroughVideo({
     // dismissal id was 'dismissed' on the first pass and a dismissed card
     // flashed for the length of a second appear-delay before hiding.
     if (!hasVideo) return undefined; // wait for data — see the id-based dep below
-    const timer = setTimeout(() => {
-      const reveal = () => {
-        if (dismissEnabled && isWalkthroughDismissed(storageKey, dismissalId)) {
-          setDismissed(true);
-          return;
-        }
-        // Cleared on the way through: a client-only embedder can swap to a NEW
-        // video id in-session (the cookie is id-matched, so the new one isn't
-        // dismissed), and a sticky `dismissed` kept the card hidden until a
-        // full reload — contradicting the id-match behaviour documented above.
-        setDismissed(false);
-        setMounted(true);
-      };
+    let delayElapsed = false;
+    let interacted = inline;
+    const reveal = () => {
+      if (dismissEnabled && isWalkthroughDismissed(storageKey, dismissalId)) {
+        setDismissed(true);
+        return;
+      }
+      // Cleared on the way through: a client-only embedder can swap to a NEW
+      // video id in-session (the cookie is id-matched, so the new one isn't
+      // dismissed), and a sticky `dismissed` kept the card hidden until a
+      // full reload — contradicting the id-match behaviour documented above.
+      setDismissed(false);
+      setMounted(true);
+    };
+    const revealWhenReady = () => {
+      if (!delayElapsed || !interacted) return;
       const ric = (window as unknown as { requestIdleCallback?: (cb: () => void) => number }).requestIdleCallback;
       if (typeof ric === 'function') idleHandle = ric(reveal);
       else reveal();
+    };
+    const stopListening = () => {
+      for (const type of FIRST_INTERACTION_EVENTS) window.removeEventListener(type, onInteraction, true);
+    };
+    function onInteraction() {
+      interacted = true;
+      stopListening();
+      revealWhenReady();
+    }
+    if (!interacted) {
+      for (const type of FIRST_INTERACTION_EVENTS) {
+        window.addEventListener(type, onInteraction, { capture: true, passive: true });
+      }
+    }
+    const timer = setTimeout(() => {
+      delayElapsed = true;
+      revealWhenReady();
     }, appearDelayMs);
     return () => {
       clearTimeout(timer);
+      stopListening();
       const cic = (window as unknown as { cancelIdleCallback?: (h: number) => void }).cancelIdleCallback;
       if (idleHandle !== null && typeof cic === 'function') cic(idleHandle);
     };
     // `videoId`, not the object: a new identity (embedder refetch, re-seeded
     // RSC payload) would otherwise restart the appear delay.
-  }, [appearDelayMs, dismissEnabled, storageKey, dismissalId, hasVideo, videoId]);
+  }, [appearDelayMs, dismissEnabled, storageKey, dismissalId, hasVideo, videoId, inline]);
 
   // --- environment preferences (read after hydration; no SSR access) ---
   // Derived, not stored: both inputs are plain reads of the environment, and

package/src/components/shared/legal-document/index.ts

@@ -8,7 +8,15 @@
 
 export {
   LegalDocumentPage,
+  legalDocumentStampLabel,
   type LegalDocumentPageProps,
   type LegalDocumentMarkdownRendererProps,
 } from './legal-document-page';
 export { useLegalDocs, type LegalDocument, type UseLegalDocsOptions, type UseLegalDocsReturn } from './use-legal-docs';
+export {
+  useLegalDocuments,
+  toLegalDocumentSummaries,
+  type LegalDocumentSummary,
+  type UseLegalDocumentsOptions,
+  type UseLegalDocumentsReturn,
+} from './use-legal-documents';

package/src/components/shared/legal-document/legal-document-page.tsx

@@ -25,6 +25,7 @@ import { FaqSection, pageFaqProps, type PageFaqSlot } from '../../faq/faq-sectio
 import { PageShell, PageLayout } from '../../ui';
 import { RichMarkdownRenderer } from '../../ui/markdown';
 import { useLegalDocs, type LegalDocument } from './use-legal-docs';
+import { useLegalDocuments } from './use-legal-documents';
 
 export interface LegalDocumentMarkdownRendererProps {
   content: string;
@@ -34,25 +35,24 @@ export interface LegalDocumentMarkdownRendererProps {
 
 export interface LegalDocumentPageProps {
   /** Document type identifier — drives the default API endpoint
-   *  `/api/legal/<docType>` AND the error-log prefix. Common values:
-   *  `'privacy'`, `'terms'`. Embedders may use any string. */
+   *  `/api/legal/<docType>` AND the error-log prefix. One of the types the
+   *  host's list answers (`useLegalDocuments`). */
   docType: string;
-  /** Heading text (e.g. "Privacy Policy", "Terms of Service"). */
-  title: string;
-  /** Fallback subtitle shown when no `lastUpdated` date is available
-   *  (e.g. "Our privacy policy and data protection practices"). */
-  fallbackDescription: string;
-  /** Email shown in the error + empty-state copy
-   *  (e.g. `'privacy@openframe.io'`, `'legal@openframe.io'`). */
-  contactEmail: string;
-  /** Prompt shown above the contact link in the error state
-   *  (e.g. "For privacy-related questions, please contact:"). */
-  errorContactPrompt: string;
-  /** Title for the error block (e.g. "Unable to load privacy policy"). */
-  errorTitle: string;
-  /** Sentence shown when the API returns no document
-   *  (e.g. "Privacy policy content is not available at this time."). */
-  emptyStateMessage: string;
+  /** Heading text. Default: the title the served document carries, so a host
+   *  that shows whatever the list holds states no per-document copy. */
+  title?: string;
+  /** Subtitle shown when the document states neither a version nor a date. */
+  fallbackDescription?: string;
+  /** Email shown in the error + empty-state copy. Absent: no contact line. */
+  contactEmail?: string;
+  /** Prompt shown above the contact link in the error state.
+   *  Default "For questions about this document, please contact:". */
+  errorContactPrompt?: string;
+  /** Title for the error block. Default "Unable to load <title>". */
+  errorTitle?: string;
+  /** Sentence shown when the API returns no document.
+   *  Default "<title> is not available at this time.". */
+  emptyStateMessage?: string;
   /** SSR-prepared document, if available. */
   initialData?: LegalDocument | null;
   /** SSR-prepared formatted "Last Updated" label. Stable across hydration. */
@@ -66,29 +66,52 @@ export interface LegalDocumentPageProps {
    *  to hide. Default `{ label: 'Back to home', href: '/' }`. */
   backButton?: { label?: string; href?: string } | false;
   /**
-   * The page's own FAQ block: the topic the page is about (stated by the host,
-   * never read from its address) and where the host serves the FAQs. Rendered
-   * after the page's content, inside its container. Absent: no FAQ block.
+   * The hub's list of legal documents (`GET /api/legal`). Given it, the page
+   * takes the document's title and FAQ topic from the list, so a host passes
+   * only the type and its endpoints and states nothing per document; the title
+   * then names the document even when its text fails to load.
    */
-  faq?: PageFaqSlot;
+  documentsEndpoint?: string;
+  /**
+   * The page's own FAQ block: the topic the page is about and where the host
+   * serves the FAQs. Rendered after the page's content, inside its container.
+   * Without a `topic`, the topic is the one the list (`documentsEndpoint`)
+   * gives the document. Absent, or no topic known: no FAQ block.
+   */
+  faq?: PageFaqSlot | Omit<PageFaqSlot, 'topic'>;
   /** Render the standalone `<PageShell>`. Default true. Pass false when the host
    *  layout already provides the page container — only the padding box renders,
    *  avoiding a nested `<main>`. */
   shell?: boolean;
 }
 
+/**
+ * "Version 1.0 · Effective October 14, 2026" for a document that states them;
+ * null for one that states neither. One wording for every legal surface.
+ */
+export function legalDocumentStampLabel(
+  doc: Pick<LegalDocument, 'version' | 'effectiveDate'> | null | undefined,
+): string | null {
+  const parts = [
+    doc?.version ? `Version ${doc.version}` : null,
+    doc?.effectiveDate ? `Effective ${doc.effectiveDate}` : null,
+  ].filter((part): part is string => part !== null);
+  return parts.length > 0 ? parts.join(' \u00b7 ') : null;
+}
+
 export function LegalDocumentPage({
   docType,
-  title,
-  fallbackDescription,
+  title: titleProp,
+  fallbackDescription = '',
   contactEmail,
-  errorContactPrompt,
-  errorTitle,
-  emptyStateMessage,
+  errorContactPrompt = 'For questions about this document, please contact:',
+  errorTitle: errorTitleProp,
+  emptyStateMessage: emptyStateMessageProp,
   initialData = null,
   initialLastUpdatedLabel = null,
   apiEndpoint,
   MarkdownRenderer = RichMarkdownRenderer,
+  documentsEndpoint,
   backButton,
   faq,
   shell = true,
@@ -107,13 +130,25 @@ export function LegalDocumentPage({
           onClick: () => router.push(backButton?.href ?? '/'),
         };
 
+  const { documents } = useLegalDocuments({ apiEndpoint: documentsEndpoint, enabled: Boolean(documentsEndpoint) });
+  const listed = documents.find(doc => doc.docType === docType);
+  const title = titleProp ?? data?.title ?? listed?.title ?? 'Legal document';
+  const faqTopic = faq && 'topic' in faq ? faq.topic : listed?.faqTopic;
+  const faqSlot = faq && faqTopic ? { ...faq, topic: faqTopic } : null;
+  const errorTitle = errorTitleProp ?? `Unable to load ${title}`;
+  const emptyStateMessage = emptyStateMessageProp ?? `${title} is not available at this time.`;
+
   const fallbackLastUpdatedLabel = data?.lastSynced != null ? formatLegalDate(data.lastSynced) : null;
   const effectiveLastUpdatedLabel = initialLastUpdatedLabel ?? fallbackLastUpdatedLabel;
 
   // Subtitle routes through the frozen `PageLayout` `TitleBlock` (text-h2 title
-  // + subtitle) — unified header across all help-center pages. Shows the
-  // last-updated date when known, else the fallback description.
-  const subtitle = effectiveLastUpdatedLabel ? `Last Updated: ${effectiveLastUpdatedLabel}` : fallbackDescription;
+  // + subtitle) — unified header across all help-center pages. A document that
+  // states its own version and effective date shows those (they are what a
+  // reader agreed to); one that states neither shows when it was last read
+  // from its source, else the fallback description.
+  const subtitle =
+    legalDocumentStampLabel(data) ??
+    (effectiveLastUpdatedLabel ? `Last Updated: ${effectiveLastUpdatedLabel}` : fallbackDescription);
 
   const inner = (
     <PageLayout title={title} subtitle={subtitle} backButton={backCfg} titleSize="h1" titleWrap>
@@ -144,32 +179,36 @@ export function LegalDocumentPage({
                     <p className="mb-2 text-ods-error">{errorTitle}</p>
                     <p className="text-ods-error text-h6">{error}</p>
                   </div>
-                  <div className="text-ods-text-secondary">
-                    <p>{errorContactPrompt}</p>
-                    <Link href={`mailto:${contactEmail}`} className="text-ods-accent hover:underline">
-                      {contactEmail}
-                    </Link>
-                  </div>
+                  {contactEmail && (
+                    <div className="text-ods-text-secondary">
+                      <p>{errorContactPrompt}</p>
+                      <Link href={`mailto:${contactEmail}`} className="text-ods-accent hover:underline">
+                        {contactEmail}
+                      </Link>
+                    </div>
+                  )}
                 </div>
               ) : data ? (
                 <MarkdownRenderer content={data.content} sectionIds={data.sections || []} demoteMarkdownH1ToH2 />
               ) : (
                 <div className="py-16 text-center text-ods-text-secondary">
                   <p className="text-h4">{emptyStateMessage}</p>
-                  <p className="mt-2">
-                    Please contact{' '}
-                    <Link href={`mailto:${contactEmail}`} className="text-ods-accent hover:underline">
-                      {contactEmail}
-                    </Link>{' '}
-                    for more information.
-                  </p>
+                  {contactEmail && (
+                    <p className="mt-2">
+                      Please contact{' '}
+                      <Link href={`mailto:${contactEmail}`} className="text-ods-accent hover:underline">
+                        {contactEmail}
+                      </Link>{' '}
+                      for more information.
+                    </p>
+                  )}
                 </div>
               )}
             </article>
           </div>
         </div>
       </div>
-      {faq && <FaqSection {...pageFaqProps(faq)} />}
+      {faqSlot && <FaqSection {...pageFaqProps(faqSlot)} />}
     </PageLayout>
   );
 

package/src/components/shared/legal-document/use-legal-docs.ts

@@ -24,6 +24,10 @@ export interface LegalDocument {
   githubSha: string | null;
   sections: Array<{ id: string; title: string; level: number }>;
   docType: string;
+  /** The version the document states for itself ("1.0"); null when it states none. */
+  version: string | null;
+  /** The day that version takes effect, as the document words it; null when it states none. */
+  effectiveDate: string | null;
   meta: {
     sectionsCount: number;
     contentLength: number;
@@ -111,6 +115,8 @@ function toLegalDocument(payload: unknown, docType: string): LegalDocument | nul
     githubSha: typeof githubSha === 'string' ? githubSha : null,
     sections,
     docType: readString(payload, 'docType') ?? docType,
+    version: readString(payload, 'version') ?? null,
+    effectiveDate: readString(payload, 'effectiveDate') ?? null,
     meta: {
       sectionsCount: typeof sectionsCount === 'number' ? sectionsCount : sections.length,
       contentLength: typeof contentLength === 'number' ? contentLength : content.length,
@@ -122,9 +128,9 @@ function toLegalDocument(payload: unknown, docType: string): LegalDocument | nul
 /**
  * Hook to fetch a legal document.
  * @param docType — short identifier for the document (drives the
- *   default endpoint path AND the error-log prefix). Common values:
- *   `'privacy'` (SECURITY.md), `'terms'` (LICENSE). Embedders may use
- *   any string — the hook treats it as opaque.
+ *   default endpoint path AND the error-log prefix). The valid values are
+ *   the ones the host's list endpoint answers (`useLegalDocuments`); the
+ *   hook treats it as opaque.
  */
 export function useLegalDocs(docType: string, options: UseLegalDocsOptions = {}): UseLegalDocsReturn {
   const { initialData = null, apiEndpoint } = options;
@@ -183,6 +189,15 @@ export function useLegalDocs(docType: string, options: UseLegalDocsOptions = {})
       try {
         const response = await contentFetch(effectiveEndpoint);
 
+        // 404: the hub has no published text for this document yet (a legal
+        // file is published only once it states its version and effective
+        // date). That is "not available", not a failure: no data, no error.
+        if (response.status === 404) {
+          if (!isCurrent()) return;
+          setData(null);
+          return;
+        }
+
         if (!response.ok) {
           throw new Error(`Failed to fetch ${docType} document: ${response.status} ${response.statusText}`);
         }

package/src/components/shared/legal-document/use-legal-documents.ts

@@ -0,0 +1,113 @@
+'use client';
+
+/**
+ * useLegalDocuments — the list of legal documents a hub publishes (privacy
+ * policy, terms of service, payment terms, license, security policy, and
+ * whatever it adds later), each with its page and the version it states.
+ *
+ * A host that lists legal pages reads this list, shows one entry per published
+ * document, each leading to that document's own page, and names no document
+ * itself: a document the hub adds appears with no change here.
+ *
+ * Endpoint: default `/api/legal`; an embedder passes its proxied path.
+ */
+
+import { useEffect, useState } from 'react';
+import { contentFetch } from '../../../utils/embed-content-fetch';
+
+export interface LegalDocumentSummary {
+  /** The identifier `useLegalDocs` and `<LegalDocumentPage>` take. */
+  docType: string;
+  title: string;
+  /** One line saying what the document is, for a card that lists it. */
+  summary: string;
+  /** The document's page on the hub's own site (a path). */
+  route: string;
+  sourceFile: string;
+  /** The topic the document's FAQs are written for, when the hub has one. */
+  faqTopic: string | null;
+  version: string | null;
+  effectiveDate: string | null;
+  /** False while the hub has no content for it yet. */
+  published: boolean;
+}
+
+export interface UseLegalDocumentsOptions {
+  /** Full GET endpoint URL. Default `/api/legal`. */
+  apiEndpoint?: string;
+  /** False: read nothing and answer an empty list. Default true. */
+  enabled?: boolean;
+}
+
+export interface UseLegalDocumentsReturn {
+  documents: LegalDocumentSummary[];
+  isLoading: boolean;
+  error: string | null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function text(source: Record<string, unknown>, key: string): string | null {
+  const value = source[key];
+  return typeof value === 'string' && value ? value : null;
+}
+
+/** Decode the endpoint's answer; a row without a type and a title is left out. */
+export function toLegalDocumentSummaries(payload: unknown): LegalDocumentSummary[] {
+  const rows: unknown = isRecord(payload) ? payload.documents : null;
+  if (!Array.isArray(rows)) return [];
+  const documents: LegalDocumentSummary[] = [];
+  for (const row of rows as readonly unknown[]) {
+    if (!isRecord(row)) continue;
+    const docType = text(row, 'docType');
+    const title = text(row, 'title');
+    if (!docType || !title) continue;
+    documents.push({
+      docType,
+      title,
+      summary: text(row, 'summary') ?? '',
+      route: text(row, 'route') ?? '',
+      sourceFile: text(row, 'sourceFile') ?? '',
+      faqTopic: text(row, 'faqTopic'),
+      version: text(row, 'version'),
+      effectiveDate: text(row, 'effectiveDate'),
+      published: row.published === true,
+    });
+  }
+  return documents;
+}
+
+export function useLegalDocuments(options: UseLegalDocumentsOptions = {}): UseLegalDocumentsReturn {
+  const endpoint = options.apiEndpoint ?? '/api/legal';
+  const enabled = options.enabled ?? true;
+  const [state, setState] = useState<UseLegalDocumentsReturn>({ documents: [], isLoading: enabled, error: null });
+
+  useEffect(() => {
+    let current = enabled;
+    const load = async () => {
+      try {
+        const response = await contentFetch(endpoint);
+        if (!response.ok) throw new Error(`Failed to fetch legal documents: ${response.status} ${response.statusText}`);
+        const payload: unknown = await response.json();
+        if (current) setState({ documents: toLegalDocumentSummaries(payload), isLoading: false, error: null });
+      } catch (err) {
+        console.error('Error fetching legal documents:', err);
+        if (current) {
+          setState({
+            documents: [],
+            isLoading: false,
+            error: err instanceof Error ? err.message : 'Unknown error occurred',
+          });
+        }
+      }
+    };
+    if (enabled) void load();
+    return () => {
+      current = false;
+    };
+  }, [endpoint, enabled]);
+
+  return state;
+}

package/src/components/ui/dropdown-button.tsx

@@ -144,7 +144,7 @@ export function DropdownButton({
           href={action.href}
           download={action.download}
           openInNewTab={action.openInNewTab}
-          onClick={action.onClick as React.MouseEventHandler<HTMLButtonElement> | undefined}
+          onClick={action.onClick}
           disabled={disabled}
           loading={loading}
           leftIcon={icon}

package/src/embed-shims/next-image.tsx

@@ -22,6 +22,8 @@
 'use client';
 import { forwardRef, type ComponentType, type ImgHTMLAttributes, type Ref } from 'react';
 
+import { fetchPriorityProp } from '../utils/fetch-priority';
+
 type ImageProps = Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'placeholder'> & {
   src?: string | { src: string };
   alt?: string;
@@ -91,12 +93,18 @@ const Image = forwardRef<HTMLImageElement, ImageProps>(function NextImageShim({
     optimizedWidth && resizer && typeof given.src === 'string'
       ? { ...given, src: resizer(given.src, optimizedWidth), unoptimized: true }
       : given;
-  // Real impl path — registered by the host. Hand off untouched so
-  // every Next-specific prop (priority, placeholder, sizes, loader…)
-  // reaches the real component intact.
+  // `priority` means "this is the picture the page is waiting for", so its
+  // request is ranked high on EVERY host. Stated here, once: since Next 16
+  // `priority` only preloads and no longer ranks the request, and the plain
+  // <img> below dropped the prop altogether, so an embedder's hero went out at
+  // the default priority. A caller that names its own `fetchPriority` keeps it.
+  const fetchPriority = props.fetchPriority ?? (props.priority ? 'high' : undefined);
+
+  // Real impl path — registered by the host. Every Next-specific prop
+  // (priority, placeholder, sizes, loader…) reaches the real component intact.
   if (impl) {
     const Real = impl;
-    return <Real ref={ref} {...props} />;
+    return <Real ref={ref} {...props} fetchPriority={fetchPriority} />;
   }
 
   // Fallback path — plain <img>. Drops Next-only props and reduces
@@ -115,6 +123,7 @@ const Image = forwardRef<HTMLImageElement, ImageProps>(function NextImageShim({
     unoptimized: _unoptimized,
     onLoadingComplete,
     loader: _loader,
+    fetchPriority: _fetchPriority,
     style,
     ...rest
   } = props;
@@ -147,6 +156,8 @@ const Image = forwardRef<HTMLImageElement, ImageProps>(function NextImageShim({
       style={finalStyle}
       onLoad={onLoadingComplete ? e => onLoadingComplete(e.currentTarget) : undefined}
       {...rest}
+      // The attribute's spelling depends on the host's React major (`fetchPriorityProp`).
+      {...(fetchPriority ? fetchPriorityProp(fetchPriority) : {})}
     />
   );
 });

package/src/utils/index.ts

@@ -415,6 +415,7 @@ export * from './humanity-signals';
 // so the host's draft endpoint re-applies the same filter the browser hook runs.
 // Also exported via the granular subpath `./utils/form-rescue`.
 export * from './form-rescue';
+export * from './legal-documents';
 
 // Doc-source viewer utilities (path parsing, tree building, section extraction,
 // embed-URL conversion) — single home for all doc-viewer pure helpers across

package/src/utils/legal-documents.ts

@@ -0,0 +1,21 @@
+/**
+ * The types of legal document a hub can publish, each with a page of its own
+ * (`/api/legal/<type>`, `<LegalDocumentPage docType>`).
+ *
+ * WHICH of them are published, and each one's title, version and effective
+ * date, is the hub's answer at run time (`GET /api/legal`, `useLegalDocuments`).
+ * This list exists for a host that must know every possible page before it
+ * runs: a statically exported app prerenders one legal page per type here and
+ * links only the ones the hub's list says are published.
+ *
+ * Pure and server-safe. The hub's own list of legal documents carries exactly
+ * these types.
+ */
+export const LEGAL_DOCUMENT_TYPES = ['privacy', 'terms', 'payment', 'license', 'security'] as const;
+
+export type LegalDocumentType = (typeof LEGAL_DOCUMENT_TYPES)[number];
+
+/** True for a type a host has a page for (one of {@link LEGAL_DOCUMENT_TYPES}). */
+export function isLegalDocumentType(value: string): value is LegalDocumentType {
+  return (LEGAL_DOCUMENT_TYPES as readonly string[]).includes(value);
+}