@gmickel/gno 1.39.2 → 1.40.0

package/src/serve/public/hooks/use-pdf-pages.ts

@@ -1,4 +1,11 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type RefObject,
+} from "react";
 
 import {
   classifyPdfError,
@@ -41,6 +48,13 @@ export type PageSlotState = {
    * mount canvas / TextLayer. Production PdfPageView `active` prop.
    */
   active: boolean;
+  /**
+   * Nonfatal geometry failure carried on this slot (R2): a later page whose
+   * `getPage` failed while page 1 succeeded. The slot keeps its placeholder
+   * size so the scroll model holds; the viewer shows the page error state in
+   * place of the page and every other slot stays mounted.
+   */
+  error: PdfFallbackReason | null;
 };
 
 export type UsePdfPagesOptions = {
@@ -54,6 +68,12 @@ export type UsePdfPagesOptions = {
   containerHeight: number;
   /** Bumped by viewer on every zoom/fit/scale commit. */
   genId: number;
+  /**
+   * Scrolling element that holds the page column. When the full geometry pass
+   * corrects placeholder heights, its `scrollTop` is adjusted by the height
+   * delta of the pages above the page in view so that page's top edge stays put.
+   */
+  scrollContainerRef?: RefObject<HTMLElement | null>;
   devicePixelRatio?: number;
   /**
    * Optional test doubles only (not a product API). Production omits these.
@@ -67,7 +87,12 @@ export type UsePdfPagesOptions = {
 
 export type UsePdfPagesResult = {
   slots: PageSlotState[];
-  /** Geometry/page acquisition failure classified for the viewer state model. */
+  /**
+   * Fatal failure classified for the viewer state model: page 1 geometry (the
+   * document behind it) or a page-1 render-path page acquisition failure. A later
+   * page's geometry or render-path acquisition failure is not fatal — it rides
+   * on `PageSlotState.error`.
+   */
   error: PdfFallbackReason | null;
   liveCanvasCount: number;
   observePage: (pageNumber: number, el: HTMLElement | null) => void;
@@ -110,6 +135,141 @@ type PageCache = {
 
 type BasePageGeometry = { width: number; height: number };
 
+type PageGeometryResult = {
+  geometry: BasePageGeometry | null;
+  /** Classified `getPage` failure for this page; `null` once measured. */
+  error: PdfFallbackReason | null;
+};
+
+/**
+ * One geometry pass over a document. Page 1 resolves alone first so the viewer
+ * can publish placeholder slots (every page at page 1's size) and paint page 1
+ * before the rest is measured; the bounded worker pass then continues from
+ * page 2 and `full` carries every page's real size or its classified failure.
+ */
+type GeometryPass = {
+  firstPage: Promise<BasePageGeometry>;
+  full: Promise<PageGeometryResult[]>;
+  /** Result of `full` once it resolved; a later effect run skips the placeholder publish. */
+  settled: PageGeometryResult[] | null;
+};
+
+const GEOMETRY_WORKERS = 4;
+
+function startGeometryPass(
+  doc: PDFDocumentProxy,
+  numPages: number
+): GeometryPass {
+  const measure = async (pageNumber: number): Promise<BasePageGeometry> => {
+    const page = await doc.getPage(pageNumber);
+    const viewport = page.getViewport({ scale: 1 });
+    return { width: viewport.width, height: viewport.height };
+  };
+  const firstPage = measure(1);
+  const full = (async (): Promise<PageGeometryResult[]> => {
+    const results = Array.from(
+      { length: numPages },
+      (): PageGeometryResult => ({ geometry: null, error: null })
+    );
+    // Page 1 is fatal: a rejection here rejects `full` as well.
+    results[0] = { geometry: await firstPage, error: null };
+    let nextPageNumber = 2;
+    const worker = async (): Promise<void> => {
+      while (nextPageNumber <= numPages) {
+        const pageNumber = nextPageNumber;
+        nextPageNumber += 1;
+        try {
+          results[pageNumber - 1] = {
+            geometry: await measure(pageNumber),
+            error: null,
+          };
+        } catch (error) {
+          // A later page's failure rides on its slot; the pass continues.
+          results[pageNumber - 1] = {
+            geometry: null,
+            error: classifyPdfError(error),
+          };
+        }
+      }
+    };
+    await Promise.all(
+      Array.from(
+        { length: Math.min(GEOMETRY_WORKERS, numPages - 1) },
+        async () => worker()
+      )
+    );
+    return results;
+  })();
+  const pass: GeometryPass = { firstPage, full, settled: null };
+  full.then(
+    (results) => {
+      pass.settled = results;
+    },
+    () => {
+      // Surfaced through `firstPage` by the effect that awaits it.
+    }
+  );
+  return pass;
+}
+
+function anchorPage(visible: ReadonlySet<number>): number | null {
+  let anchor: number | null = null;
+  for (const pageNumber of visible) {
+    if (anchor === null || pageNumber < anchor) {
+      anchor = pageNumber;
+    }
+  }
+  return anchor;
+}
+
+/**
+ * Page whose top edge straddles the viewport top, derived from laid-out boxes
+ * rather than the IntersectionObserver visible set (that set uses a 200px
+ * rootMargin and can include a page entirely above the viewport).
+ *
+ * Measures the DOM — including `.gno-pdf-page` 1rem margin and the column's
+ * padding — instead of reconstructing offsets from slot heights plus CSS
+ * constants. Returns null when the measurement is unusable: fewer than two
+ * registered pages, or offsets that are not strictly increasing (happy-dom
+ * and a not-yet-laid-out DOM return zero rects).
+ */
+function anchorPageFromLayout(
+  container: HTMLElement,
+  elements: ReadonlyMap<number, HTMLElement>,
+  numPages: number
+): number | null {
+  const pages: number[] = [];
+  const offsets: number[] = [];
+  const containerTop = container.getBoundingClientRect().top;
+  for (let pageNumber = 1; pageNumber <= numPages; pageNumber += 1) {
+    const el = elements.get(pageNumber);
+    if (!el) {
+      continue;
+    }
+    pages.push(pageNumber);
+    offsets.push(
+      el.getBoundingClientRect().top - containerTop + container.scrollTop
+    );
+  }
+  if (pages.length < 2) {
+    return null;
+  }
+  for (let index = 1; index < offsets.length; index += 1) {
+    if (!(offsets[index]! > offsets[index - 1]!)) {
+      return null;
+    }
+  }
+  const edge = container.scrollTop + 0.5;
+  // No qualifying page means the reader is above page 1.
+  let anchor = 1;
+  for (let index = 0; index < pages.length; index += 1) {
+    if (offsets[index]! <= edge) {
+      anchor = pages[index]!;
+    }
+  }
+  return anchor;
+}
+
 function setsEqual(a: ReadonlySet<number>, b: ReadonlySet<number>): boolean {
   if (a.size !== b.size) {
     return false;
@@ -165,6 +325,7 @@ export function usePdfPages(options: UsePdfPagesOptions): UsePdfPagesResult {
     containerWidth,
     containerHeight,
     genId,
+    scrollContainerRef,
     devicePixelRatio = typeof window !== "undefined"
       ? window.devicePixelRatio || 1
       : 1,
@@ -189,9 +350,12 @@ export function usePdfPages(options: UsePdfPagesOptions): UsePdfPagesResult {
   const canvasRef = useRef<Map<number, HTMLCanvasElement>>(new Map());
   const reservationsRef = useRef<Map<number, symbol>>(new Map());
   const latestRequestRef = useRef<Map<number, symbol>>(new Map());
-  const geometryCacheRef = useRef<
-    WeakMap<PDFDocumentProxy, Promise<BasePageGeometry[]>>
-  >(new WeakMap());
+  // Holds the full pass only: the placeholder slots derived from page 1 are a
+  // transient publish, never cached geometry. `firstPage` is that pass's own
+  // page-1 prefix, so a re-run during the pass can still publish early.
+  const geometryCacheRef = useRef<WeakMap<PDFDocumentProxy, GeometryPass>>(
+    new WeakMap()
+  );
   const observerRef = useRef<IntersectionObserver | null>(null);
   const settledTaskIdsRef = useRef<Set<string>>(new Set());
   const metrics = getPdfMetrics();
@@ -238,28 +402,37 @@ export function usePdfPages(options: UsePdfPagesOptions): UsePdfPagesResult {
     }
   }, []);
 
+  const openEpoch = (): void => {
+    epochSeqRef.current += 1;
+    epochBatchOpenRef.current = true;
+    epochAdmittedRef.current = 0;
+    pendingRef.current.clear();
+    reservationsRef.current.clear();
+    latestRequestRef.current.clear();
+    if (pendingTimerRef.current !== null) {
+      clearTimeout(pendingTimerRef.current);
+      pendingTimerRef.current = null;
+    }
+  };
+
   // Synchronous epoch bump (same pattern as genIdRef above): a doc or gen change
   // must open its exempt batch before any render path observes the new state.
   {
     const epochKey = `${docId ?? ""}:${genId}`;
     if (epochKeyRef.current !== epochKey) {
       epochKeyRef.current = epochKey;
-      epochSeqRef.current += 1;
-      epochBatchOpenRef.current = true;
-      epochAdmittedRef.current = 0;
-      pendingRef.current.clear();
-      reservationsRef.current.clear();
-      latestRequestRef.current.clear();
-      if (pendingTimerRef.current !== null) {
-        clearTimeout(pendingTimerRef.current);
-        pendingTimerRef.current = null;
-      }
+      openEpoch();
     }
   }
   const scaleRef = useRef(scale);
   scaleRef.current = scale;
   const visibleRef = useRef(visiblePages);
   visibleRef.current = visiblePages;
+  /** Slots as last rendered — the heights the DOM currently shows. */
+  const slotsRef = useRef(slots);
+  slotsRef.current = slots;
+  /** Scroll delta to apply once the corrected slot heights are in the DOM. */
+  const pendingScrollAdjustRef = useRef(0);
   const disposedRef = useRef(false);
   const disposePromiseRef = useRef<Promise<void> | null>(null);
 
@@ -287,9 +460,12 @@ export function usePdfPages(options: UsePdfPagesOptions): UsePdfPagesResult {
     [numPages]
   );
 
-  // Resolve rotation-aware geometry with bounded concurrency before publishing
-  // slots. Correct placeholders are part of the scroll model: copying page 1
-  // makes mixed-size documents jump and makes fit modes overflow later pages.
+  // Rotation-aware geometry drives the scroll model. Slots publish as soon as
+  // page 1 is measured (every page at page 1's size, fit scale from page 1) so
+  // the first paint does not wait for the rest of the document; the full pass
+  // then corrects sizes and the fit scale in one commit, anchored so the page
+  // in view does not jump. Copying page 1 is only ever the placeholder:
+  // mixed-size documents and fit modes settle on the real per-page sizes.
   useEffect(() => {
     let cancelled = false;
     if (!doc || numPages === 0) {
@@ -299,75 +475,15 @@ export function usePdfPages(options: UsePdfPagesOptions): UsePdfPagesResult {
       return;
     }
 
-    void (async () => {
-      let geometryPromise = geometryCacheRef.current.get(doc);
-      if (!geometryPromise) {
-        geometryPromise = (async (): Promise<BasePageGeometry[]> => {
-          const geometry = Array.from<BasePageGeometry | undefined>({
-            length: numPages,
-          });
-          let nextPageNumber = 1;
-          let failure: unknown = null;
-          const worker = async (): Promise<void> => {
-            while (failure === null) {
-              const pageNumber = nextPageNumber;
-              nextPageNumber += 1;
-              if (pageNumber > numPages) {
-                return;
-              }
-              try {
-                const page = await doc.getPage(pageNumber);
-                if (failure !== null) {
-                  return;
-                }
-                const viewport = page.getViewport({ scale: 1 });
-                geometry[pageNumber - 1] = {
-                  width: viewport.width,
-                  height: viewport.height,
-                };
-              } catch (error) {
-                failure = error;
-              }
-            }
-          };
-          await Promise.all(
-            Array.from({ length: Math.min(4, numPages) }, async () => worker())
-          );
-          const resolved = geometry.filter(
-            (entry): entry is BasePageGeometry => entry !== undefined
-          );
-          if (failure !== null) {
-            throw failure;
-          }
-          if (resolved.length !== numPages) {
-            throw new Error("PDF page geometry is incomplete");
-          }
-          return resolved;
-        })();
-        geometryCacheRef.current.set(doc, geometryPromise);
-      }
-
-      let resolvedGeometry: BasePageGeometry[];
-      try {
-        resolvedGeometry = await geometryPromise;
-      } catch (error) {
-        if (cancelled) {
-          return;
-        }
-        setSlots([]);
-        setPageError(classifyPdfError(error));
-        return;
-      }
-      if (cancelled) {
-        return;
-      }
-
-      const maxWidth = Math.max(
-        ...resolvedGeometry.map((entry) => entry.width)
-      );
-      const maxHeight = Math.max(
-        ...resolvedGeometry.map((entry) => entry.height)
-      );
+    const commit = (
+      results: PageGeometryResult[],
+      placeholder: BasePageGeometry,
+      correction: boolean,
+      placeholderScale?: number
+    ): number => {
+      const sizes = results.map((entry) => entry.geometry ?? placeholder);
+      const maxWidth = Math.max(...sizes.map((entry) => entry.width));
+      const maxHeight = Math.max(...sizes.map((entry) => entry.height));
       let nextScale = zoom;
       if (fitMode === "width" && containerWidth > 0) {
         nextScale = containerWidth / maxWidth;
@@ -382,21 +498,114 @@ export function usePdfPages(options: UsePdfPagesOptions): UsePdfPagesResult {
         );
       }
       nextScale = Math.max(0.25, Math.min(4, nextScale));
-      setScale(nextScale);
-      setPageError(null);
 
       const visible = visibleRef.current;
       const active = computeActiveSet(visible, numPages);
-      setSlots(
-        resolvedGeometry.map((entry, index) => ({
+      const next = sizes.map(
+        (entry, index): PageSlotState => ({
           pageNumber: index + 1,
           width: entry.width * nextScale,
           height: entry.height * nextScale,
           rendered: false,
           visible: visible.has(index + 1),
           active: active.has(index + 1),
-        }))
+          error: results[index]?.error ?? null,
+        })
       );
+
+      if (correction) {
+        // Keep the top edge of the page straddling the viewport top where it
+        // is: shift scrollTop by the height delta of pages strictly above that
+        // page, applied once the new heights are in the DOM. The anchor is
+        // read from laid-out boxes here only (DOM includes page margin and
+        // column padding); the observer set is the fallback when layout is
+        // unusable or the scroll container is missing.
+        const shown = slotsRef.current;
+        const container = scrollContainerRef?.current;
+        const layoutAnchor =
+          container == null
+            ? null
+            : anchorPageFromLayout(container, elementsRef.current, numPages);
+        const anchor = layoutAnchor ?? anchorPage(visible);
+        if (anchor !== null && shown.length === next.length) {
+          let delta = 0;
+          for (let index = 0; index < anchor - 1; index += 1) {
+            delta += next[index]!.height - shown[index]!.height;
+          }
+          pendingScrollAdjustRef.current += delta;
+        }
+      }
+
+      // Same scale as the placeholder publish: a page already drawn stays
+      // drawn. Compare against the scale that commit actually returned, not
+      // scaleRef — that ref is stale if the full pass settles before React
+      // re-rendered after the placeholder.
+      const keepRendered = nextScale === (placeholderScale ?? nextScale);
+      if (correction && !keepRendered) {
+        // The correction is a scale commit like a zoom, so it opens a new
+        // admission epoch and the exempt batch admits every active page immediately.
+        openEpoch();
+      }
+      setScale(nextScale);
+      if (!correction) {
+        // Geometry recovered: the placeholder commit clears any earlier
+        // geometry error. The correction never clears, so a fatal error raised
+        // by a page 1 render attempt during the placeholder window stays.
+        setPageError(null);
+        setSlots(next);
+        return nextScale;
+      }
+      setSlots((prev) =>
+        next.map((slot, index) =>
+          keepRendered && prev[index]?.pageNumber === slot.pageNumber
+            ? { ...slot, rendered: prev[index].rendered }
+            : slot
+        )
+      );
+      return nextScale;
+    };
+
+    void (async () => {
+      let pass = geometryCacheRef.current.get(doc);
+      if (!pass) {
+        pass = startGeometryPass(doc, numPages);
+        geometryCacheRef.current.set(doc, pass);
+      }
+
+      let firstPage: BasePageGeometry;
+      try {
+        firstPage = await pass.firstPage;
+      } catch (error) {
+        if (cancelled) {
+          return;
+        }
+        // Page 1 (or the document behind it) failed: fatal, existing fallback.
+        setSlots([]);
+        setPageError(classifyPdfError(error));
+        return;
+      }
+      if (cancelled) {
+        return;
+      }
+
+      const publishedPlaceholder = pass.settled === null;
+      let placeholderScale = 1;
+      if (publishedPlaceholder) {
+        placeholderScale = commit(
+          Array.from(
+            { length: numPages },
+            (): PageGeometryResult => ({ geometry: null, error: null })
+          ),
+          firstPage,
+          false
+        );
+      }
+
+      const results = await pass.full;
+      if (cancelled) {
+        return;
+      }
+      commit(results, firstPage, publishedPlaceholder, placeholderScale);
     })();
 
     return () => {
@@ -404,6 +613,19 @@ export function usePdfPages(options: UsePdfPagesOptions): UsePdfPagesResult {
     };
   }, [doc, numPages, zoom, fitMode, containerWidth, containerHeight]);
 
+  // Apply the anchored scroll shift in the same frame the corrected heights land.
+  useLayoutEffect(() => {
+    const delta = pendingScrollAdjustRef.current;
+    if (delta === 0) {
+      return;
+    }
+    pendingScrollAdjustRef.current = 0;
+    const container = scrollContainerRef?.current;
+    if (container) {
+      container.scrollTop += delta;
+    }
+  }, [slots, scrollContainerRef]);
+
   // IntersectionObserver drives visibility → slot.active/visible → PdfPageView.
   useEffect(() => {
     if (!IntersectionObserverImpl) {
@@ -837,6 +1059,16 @@ export function usePdfPages(options: UsePdfPagesOptions): UsePdfPagesResult {
           page = await doc.getPage(pageNumber);
         } catch (error) {
           releaseReservation();
+          if (pageNumber > 1) {
+            setSlots((prev) =>
+              prev.map((s) =>
+                s.pageNumber === pageNumber
+                  ? { ...s, error: classifyPdfError(error), rendered: false }
+                  : s
+              )
+            );
+            return;
+          }
           setPageError(classifyPdfError(error));
           return;
         }

package/src/serve/public/lib/pdf-transport.ts

@@ -0,0 +1,13 @@
+/**
+ * PDF transport tier constants (fn-136 R1).
+ *
+ * Kept free of any pdfjs-dist import so tooling that runs under plain Bun
+ * (for example the Playwright smoke in scripts/pdf-viewer-smoke.ts) can read
+ * the product bounds without evaluating the browser-only pdf.js build.
+ * `./pdf` re-exports both names, so app code keeps importing from the facade.
+ */
+
+/** Files whose HEAD Content-Length is under this load in one GET. */
+export const PDF_WHOLE_FILE_MAX_BYTES = 8 * 1024 * 1024;
+/** Range chunk size for files at or above the whole-file bound. */
+export const PDF_RANGE_CHUNK_BYTES = 1024 * 1024;

package/src/serve/public/lib/pdf.ts

@@ -16,6 +16,11 @@ import {
   type PageViewport,
 } from "pdfjs-dist";
 
+import {
+  PDF_RANGE_CHUNK_BYTES,
+  PDF_WHOLE_FILE_MAX_BYTES,
+} from "./pdf-transport";
+
 // ── Worker / asset bootstrap ────────────────────────────────────────────────
 //
 // Browser (and Electrobun webview) production: same-origin /vendor/pdfjs/* routes.
@@ -124,12 +129,76 @@ export type PdfAnnotation = {
 
 // ── Document load wrapper ───────────────────────────────────────────────────
 
+/**
+ * Transport tier for one document load (fn-136 R1).
+ * - `whole-file`: one GET, ranges disabled, body streamed as it arrives.
+ * - `ranged`: Range requests of PDF_RANGE_CHUNK_BYTES with background fetch.
+ */
+export type PdfTransportHint = "whole-file" | "ranged";
+
 export type GnoGetDocumentParams = {
   url: string;
+  /** Omitted → `ranged`: chunked transport, safe for an unknown or large file. */
+  transport?: PdfTransportHint;
   // Intentionally NO caller-controlled document id — every load mints a fresh
   // opaque instance id internally (I2-6 / Sol rereview).
 };
 
+/** pdf.js DocumentInitParameters subset that the transport tier controls. */
+export type PdfTransportOptions = {
+  disableRange?: boolean;
+  rangeChunkSize?: number;
+  disableStream: boolean;
+  disableAutoFetch: boolean;
+};
+
+/**
+ * Map a transport hint to pdf.js transport options.
+ *
+ * whole-file: with `disableStream: true` pdf.js cancels the full-body reader
+ * as soon as the server advertises byte ranges, so the single-request tier
+ * must disable ranges explicitly or its first GET is thrown away.
+ *
+ * ranged: `disableStream: true` keeps the full-body GET from competing with
+ * Range requests; `disableAutoFetch: false` lets pdf.js pull the remaining
+ * chunks in the background instead of one round trip per parser miss. Range
+ * eligibility still needs Content-Length > 2×rangeChunkSize plus
+ * Accept-Ranges: bytes (emitted by GET /api/doc-asset).
+ */
+export function transportOptionsFor(
+  hint: PdfTransportHint
+): PdfTransportOptions {
+  if (hint === "whole-file") {
+    return {
+      disableRange: true,
+      disableStream: false,
+      disableAutoFetch: false,
+    };
+  }
+  return {
+    rangeChunkSize: PDF_RANGE_CHUNK_BYTES,
+    disableStream: true,
+    disableAutoFetch: false,
+  };
+}
+
+/**
+ * Pick the transport tier from a HEAD-probed Content-Length.
+ * Unknown (null / non-finite / negative) sizes fall back to `ranged`.
+ */
+export function transportHintForContentLength(
+  contentLength: number | null
+): PdfTransportHint {
+  if (
+    contentLength === null ||
+    !Number.isFinite(contentLength) ||
+    contentLength < 0
+  ) {
+    return "ranged";
+  }
+  return contentLength < PDF_WHOLE_FILE_MAX_BYTES ? "whole-file" : "ranged";
+}
+
 /**
  * Loading task augmented with the opaque per-load document instance id.
  * `gnoDocId` is never derived from URL/path/URI/filename/title/content and is
@@ -180,16 +249,8 @@ export function getDocument(
     // hits standardFontDataUrl, breaking the offline standard-font contract.
     // Force pdfjs-dist standard_fonts/* over same-origin routes instead.
     useSystemFonts: false,
-    // Range-mode loading (product policy, not a test accommodation).
-    // With disableStream, pdfjs-dist cancels the full-body reader as soon as
-    // response headers arrive when ranges are supported, so every subsequent
-    // byte is fetched as a discrete Range request (pdf.mjs PDFFetchStreamReader).
-    // disableAutoFetch keeps pdf.js from eagerly pulling the remaining chunks —
-    // correct for a windowed/virtualized viewer that only paints a bounded page
-    // window. Range eligibility still requires Content-Length > 2×rangeChunkSize
-    // plus Accept-Ranges: bytes (already emitted by GET /api/doc-asset).
-    disableStream: true,
-    disableAutoFetch: true,
+    // Transport tier by file size (fn-136 R1); see transportOptionsFor.
+    ...transportOptionsFor(params.transport ?? "ranged"),
     // Never enable embedded PDF scripting.
     // enableScripting is intentionally omitted (defaults false).
     // pdfjs v5 removed the former eval-support flag; CSP enforces no unsafe-eval.
@@ -335,6 +396,12 @@ export function isRenderingCancelled(err: unknown): boolean {
   return msg.includes("rendering cancelled") || msg.includes("cancelled");
 }
 
+// ── Transport tier constants (fn-136 R1) ────────────────────────────────────
+// Defined in ./pdf-transport (no pdfjs-dist import) and re-exported here so
+// the facade stays the single import surface for app code.
+
+export { PDF_RANGE_CHUNK_BYTES, PDF_WHOLE_FILE_MAX_BYTES };
+
 // ── Zoom / fit / canvas cap math ────────────────────────────────────────────
 
 export const MIN_ZOOM = 0.25;

package/src/serve/public/lib/server-capabilities.ts

@@ -0,0 +1,19 @@
+/** Shared client view of GET /api/capabilities. */
+
+import { apiFetch } from "../hooks/use-api";
+
+export interface ServerCapabilities {
+  bm25: boolean;
+  vector: boolean;
+  hybrid: boolean;
+  answer: boolean;
+  /** True only for a same-host client; a proxied or forwarded request is remote. */
+  localClient: boolean;
+}
+
+export function fetchServerCapabilities(): Promise<{
+  data: ServerCapabilities | null;
+  error: string | null;
+}> {
+  return apiFetch<ServerCapabilities>("/api/capabilities");
+}