@flamingo-stack/openframe-frontend-core 0.0.739 → 0.0.741

package/src/components/product-demo/product-screen.tsx

@@ -21,13 +21,15 @@ export const PRODUCT_SCREEN_COMPACT_HEIGHT = 300;
  * host's readable width: the device list's customer column breaks a name
  * mid-word below it, and the logs table beside its open drawer has no room
  * for the message; the software form is laid out wide so the package, the
- * schedule and the picked devices all fit the frame's height. A frame never
+ * schedule and the picked devices all fit the frame's height; the scripts
+ * screen puts a schedule's name, its timing and its repeat on one row. A frame never
  * lays such a screen out narrower.
  */
 const MIN_LAYOUT_WIDTH: Partial<Record<ProductScreenKey, number>> = {
   devices: 1120,
   logs: 1120,
   'software-update': 1400,
+  scripts: 1400,
 };
 
 /**

package/src/components/product-demo/registry.ts

@@ -17,4 +17,5 @@ export const PRODUCT_SCREEN_LOADERS: Record<ProductScreenKey, ProductScreenLoade
   'tickets-board': () => import('./screens/tickets-board'),
   logs: () => import('./screens/logs'),
   knowledge: () => import('./screens/knowledge'),
+  scripts: () => import('./screens/scripts'),
 };

package/src/components/product-demo/screen-keys.ts

@@ -15,6 +15,7 @@ export const PRODUCT_SCREEN_LABELS = {
   'tickets-board': 'Ticket board',
   logs: 'Logs with a log open',
   knowledge: 'Knowledge base',
+  scripts: 'Script library and schedules',
 } as const;
 
 export type ProductScreenKey = keyof typeof PRODUCT_SCREEN_LABELS;

package/src/components/product-demo/screens/scripts.tsx

@@ -0,0 +1,192 @@
+'use client';
+
+import { useMemo } from 'react';
+import {
+  EXECUTION_COLUMNS,
+  ScriptExecutionResult,
+  ScriptExecutionsTable,
+  type ScriptExecutionTableRow,
+  ScriptShellBadge,
+  type ScriptsTableColumnLayout,
+} from '../../features/scripts';
+import { TimerIcon } from '../../icons-v2-generated/date-and-time/timer-icon';
+import { TruncateText } from '../../ui/truncate-text';
+import { useProductDemoCast } from '../cast';
+import { buildScriptsFixture, type DemoScript } from '../fixtures/scripts';
+import type { ProductScreenViewProps } from '../types';
+
+/**
+ * The picture has nowhere to open a run and no row menu, and the Result
+ * column would repeat the output opened under its row.
+ */
+const WIDE_HIDDEN_COLUMNS = ['result', 'open'];
+
+/**
+ * A card's width hides the device column (the product's page drops it below
+ * `lg`), and the device is what the narrow picture is about: here it takes
+ * the room, with the status beside it.
+ */
+const COMPACT_COLUMNS: readonly ScriptsTableColumnLayout[] = [
+  { ...EXECUTION_COLUMNS.machineId, width: 'flex-1 min-w-0', hideAt: undefined },
+  EXECUTION_COLUMNS.status,
+];
+const COMPACT_ROWS = 4;
+
+type TokenKind = 'comment' | 'keyword' | 'string' | 'variable' | 'command' | 'parameter' | 'number' | 'plain';
+
+/**
+ * PowerShell token colours: the product editor's `ods-dark` highlight style
+ * (`script-editor-view.tsx`) in ODS tokens. Keywords yellow, strings and
+ * variables cyan, commands green, numbers amber, parameters grey, comments
+ * muted.
+ */
+const TOKEN_CLASS: Record<TokenKind, string> = {
+  comment: 'italic text-ods-text-tertiary',
+  keyword: 'text-ods-warning',
+  string: 'text-ods-flamingo-cyan',
+  variable: 'text-ods-flamingo-cyan',
+  command: 'text-ods-success',
+  parameter: 'text-ods-text-secondary',
+  number: 'text-ods-open-yellow',
+  plain: 'text-ods-text-primary',
+};
+
+/** One group per kind, in {@link TOKEN_KINDS} order; a comment or a string swallows what it contains. */
+const TOKEN_PATTERN =
+  /(#.*$)|("(?:[^"\\]|\\.)*"|'[^']*')|(\$[\w:]+)|\b(foreach|in|if|else|exit|return|param)\b|\b([A-Z][a-z]+-[A-Z][A-Za-z]+)\b|(-[A-Za-z]+)\b|\b(\d+(?:GB|MB|KB)?)\b/g;
+const TOKEN_KINDS: readonly TokenKind[] = [
+  'comment',
+  'string',
+  'variable',
+  'keyword',
+  'command',
+  'parameter',
+  'number',
+];
+
+interface Token {
+  text: string;
+  kind: TokenKind;
+}
+
+/** One line of PowerShell as coloured runs. Only the picture's own script is read, so the rules are few. */
+function tokenize(line: string): Token[] {
+  const tokens: Token[] = [];
+  let last = 0;
+  for (const match of line.matchAll(TOKEN_PATTERN)) {
+    const start = match.index ?? 0;
+    if (start > last) tokens.push({ text: line.slice(last, start), kind: 'plain' });
+    const group = match.slice(1).findIndex(Boolean);
+    tokens.push({ text: match[0], kind: TOKEN_KINDS[group] ?? 'plain' });
+    last = start + match[0].length;
+  }
+  if (last < line.length) tokens.push({ text: line.slice(last), kind: 'plain' });
+  return tokens;
+}
+
+/**
+ * The script as the product's details page shows it: its name and shell over
+ * the editor's read-only view. The product's editor is CodeMirror, which the
+ * library does not carry, so this draws the editor's geometry (a 46px number
+ * gutter, the code 32px past it, 22px rows of 14px mono) in its colours. The
+ * header adds the schedule that runs the script and who wrote and approved
+ * it: the two things the conversation beside the picture settled.
+ */
+function ScriptCodePicture({ script }: { script: DemoScript }) {
+  // Keyed by line number: the script never changes under the picture.
+  const lines = useMemo(
+    () => script.code.split('\n').map((line, index) => ({ number: index + 1, tokens: tokenize(line) })),
+    [script.code],
+  );
+  const { schedule, provenance } = script;
+  return (
+    <section
+      aria-label={script.name}
+      className="flex h-full min-w-0 flex-col overflow-hidden rounded-[8px] border border-ods-border bg-ods-card"
+    >
+      <div className="flex flex-col gap-[var(--spacing-system-xxs)] border-b border-ods-border p-[var(--spacing-system-m)]">
+        <div className="flex min-w-0 items-center justify-between gap-[var(--spacing-system-m)]">
+          <TruncateText variant="h4">{script.name}</TruncateText>
+          <span className="flex shrink-0 items-center gap-[var(--spacing-system-xxs)] text-ods-text-primary text-h6">
+            <TimerIcon className="size-4 text-ods-text-secondary" />
+            {`${schedule.repeat} ${schedule.time} · ${schedule.deviceCount} devices`}
+          </span>
+        </div>
+        <div className="flex min-w-0 items-center justify-between gap-[var(--spacing-system-m)]">
+          <TruncateText variant="h6" tone="secondary">
+            {`Written by ${provenance.author} · approved by ${provenance.approver}`}
+          </TruncateText>
+          <ScriptShellBadge
+            value={script.shellType}
+            className="shrink-0 text-ods-text-secondary text-h6"
+            iconClassName="size-4"
+          />
+        </div>
+      </div>
+      <pre className="m-0 min-h-0 flex-1 overflow-hidden bg-ods-bg py-3 font-mono text-[14px] leading-[22px]">
+        {lines.map(line => (
+          <div key={line.number} className="flex">
+            <span className="w-[46px] shrink-0 select-none pr-[4px] text-right text-ods-text-tertiary">
+              {line.number}
+            </span>
+            <code className="whitespace-pre pl-[32px]">
+              {line.tokens.map((token, at) => (
+                <span key={`${at}-${token.text}`} className={TOKEN_CLASS[token.kind]}>
+                  {token.text}
+                </span>
+              ))}
+            </code>
+          </div>
+        ))}
+      </pre>
+    </section>
+  );
+}
+
+/**
+ * Where the page's Mingo conversation leaves off: the script it wrote, on the
+ * left, and the first night its schedule ran, on the right, as the product's
+ * Execution History (a run still going, one failed, one finished with its
+ * output open under it: what it cleaned and what it freed). The schedule form
+ * and the library are the conversation's part, so the picture leaves them
+ * out. The narrow rendering is the run alone: which devices, and how each went.
+ */
+export default function ScriptsScreen({ compact = false }: ProductScreenViewProps) {
+  const cast = useProductDemoCast();
+  const fixture = useMemo(() => buildScriptsFixture(cast), [cast]);
+
+  if (compact) {
+    return (
+      // Four runs of the card's row height fill the frame; the padding is what is left round them.
+      <div className="h-full overflow-hidden bg-ods-bg p-[var(--spacing-system-xsf)]">
+        <ScriptExecutionsTable
+          rows={fixture.executions.slice(0, COMPACT_ROWS)}
+          columns={COMPACT_COLUMNS}
+          showHeader={false}
+          compact
+        />
+      </div>
+    );
+  }
+
+  const renderOutput = (row: ScriptExecutionTableRow) =>
+    row.id === fixture.openExecutionId ? <ScriptExecutionResult result={row.result} empty="—" /> : null;
+
+  return (
+    // The frame's tighter padding and no header row: the output opened under a run needs the height.
+    <div className="flex h-full gap-[var(--spacing-system-m)] overflow-hidden bg-ods-bg p-[var(--spacing-system-m)]">
+      <div className="w-[39%] shrink-0">
+        <ScriptCodePicture script={fixture.script} />
+      </div>
+      <div className="min-w-0 flex-1 overflow-hidden">
+        <ScriptExecutionsTable
+          rows={fixture.executions}
+          hideColumns={WIDE_HIDDEN_COLUMNS}
+          renderSubRow={renderOutput}
+          showHeader={false}
+          compact
+        />
+      </div>
+    </div>
+  );
+}

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/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);
+}