@tuwaio/docs-ui 0.3.3 → 0.4.0

package/README.md

@@ -12,8 +12,10 @@
 - **Nextra layout parts:** `Navbar` and `Footer` wrap the navbar and footer of `nextra-theme-docs` with the site logo and a row of external links (`baseNavLinks`, `baseFooterLinks` are the defaults: the npm and GitHub organizations of TUWA). The footer also links the policies in force on tuwa.io and the list of all policies on the docs hub.
 - **Logo:** `RemoteLogo` is an async React Server Component that fetches an SVG (by default the TUWA logo) and renders it as React elements, so it takes `className` and `currentColor`.
 - **Theme switch:** `ThemeSwitcher` is a light/dark switch for any theme state (for example `next-themes`).
+- **Interface settings for 30 days:** `PreferenceExpiry` is an inline script for the `<head>` of a site's root layout. It forgets the Local Storage values of the given keys (by default `theme`) 30 days after they were written, as the [Cookie Policy](https://tuwa.io/cookie) states, and dates each later write, whatever library writes it (`next-themes`, the `Tabs` of Nextra).
 - **Decoration:** `Orb` (an animated sphere in the brand color of a TUWA project), `StarryBackground` (an animated star field on a canvas) and `NoSSR` (renders its children only on the client).
 - **Policy pages:** `policies` lists the TUWA policies (Terms, Privacy, Cookie, Refund, Security, Data Processing Addendum) with their paths and whether they are in force (`publishedPolicies`; footers use `footerPolicies`). `loadPolicy` loads the text of a policy, and `PolicyDocument` renders it with the date of the version, a Download PDF button, anchored sections and a list of sections. The texts and PDFs come from [`TuwaIO/workflows/docs`](https://github.com/TuwaIO/workflows/tree/main/docs). Code that needs only the list or `loadPolicy` (footers, sitemaps, route handlers) imports them from `@tuwaio/docs-ui/policies`, which has no React, Next.js or Nextra imports.
+- **Search index:** the `tuwa-docs-search-index` command builds the [Pagefind](https://pagefind.app) index that the Nextra search loads from `/_pagefind`, from the pages `next build` prerendered. It reads both places Next.js keeps them: `.next/server/app` and, in builds with a deployment adapter (Next.js 16.3.8 and later on Vercel), `.next/server/route-cache`, where `pagefind --site .next/server/app` finds no pages.
 - **Stylesheet:** `dist/index.css` contains the `--tuwa-*` theme variables of [`@tuwaio/nova-core`](https://stories.tuwa.io/?path=/docs/packages-nova-core-overview--docs) (light and `.dark`), the styles of the Nextra parts and the Tailwind CSS v4 utilities used by the components, prefixed with `tuwadocs:`.
 
 ---
@@ -41,7 +43,8 @@ Import the stylesheet after the Nextra theme:
 The root layout of a TUWA documentation site:
 
 ```tsx
-import { baseNavLinks, Footer, Navbar, RemoteLogo } from '@tuwaio/docs-ui';
+import { baseNavLinks, Footer, Navbar, PreferenceExpiry, RemoteLogo } from '@tuwaio/docs-ui';
+import { Head } from 'nextra/components';
 import { getPageMap } from 'nextra/page-map';
 import { Layout } from 'nextra-theme-docs';
 import type { ReactNode } from 'react';
@@ -60,6 +63,9 @@ const navLinks = [
 export default async function RootLayout({ children }: { children: ReactNode }) {
   return (
     <html lang="en" suppressHydrationWarning>
+      <Head>
+        <PreferenceExpiry keys={['theme']} />
+      </Head>
       <body>
         <Layout
           navbar={<Navbar logo={logo} links={navLinks} />}
@@ -115,11 +121,29 @@ export function PolicyLinks() {
 
 Sections have stable anchors (`/refund#how-to-request-a-refund`), so hints and FAQ answers can link to a section.
 
+### Search index
+
+Run the command after `next build`. It uses the `pagefind` package of the site, so add it to the site's dependencies:
+
+```json
+{
+  "scripts": {
+    "build": "next build && pnpm postbuild",
+    "postbuild": "tuwa-docs-search-index"
+  },
+  "dependencies": {
+    "pagefind": "^1.5.2"
+  }
+}
+```
+
+It writes the index to `public/_pagefind` (keep that directory in `.gitignore`) with the same URLs as `pagefind --site .next/server/app`, and fails when the build has no prerendered pages.
+
 ---
 
 ## 🗄️ Browser Storage
 
-Nothing. `ThemeSwitcher` only calls `onToggle`; the site keeps the theme.
+`ThemeSwitcher` stores nothing; it only calls `onToggle`, and the site keeps the theme. `PreferenceExpiry` stores `<key>:expires` (the time in epoch milliseconds) next to each key it is given, removes both once that time has passed, and wraps `Storage.prototype.setItem` on the page to date later writes of those keys.
 
 ## 🌐 External Services
 

package/bin/search-index.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// `tuwa-docs-search-index`: the postbuild step of the TUWA documentation sites, after `next build` (see README)
+import { buildSearchIndex } from '../dist/searchIndex.js';
+
+buildSearchIndex().then(
+  ({ urls }) => console.log(`Pagefind: indexed ${urls.length} pages into public/_pagefind`),
+  (error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  },
+);

package/dist/components/Logo.d.cts

@@ -21,4 +21,5 @@ interface RemoteLogoProps extends React__default.SVGProps<SVGSVGElement> {
  */
 declare function RemoteLogo({ url, className, style, ...props }: RemoteLogoProps): Promise<string | React__default.JSX.Element>;
 
-export { RemoteLogo, type RemoteLogoProps };
+export { RemoteLogo };
+export type { RemoteLogoProps };

package/dist/components/Logo.d.ts

@@ -21,4 +21,5 @@ interface RemoteLogoProps extends React__default.SVGProps<SVGSVGElement> {
  */
 declare function RemoteLogo({ url, className, style, ...props }: RemoteLogoProps): Promise<string | React__default.JSX.Element>;
 
-export { RemoteLogo, type RemoteLogoProps };
+export { RemoteLogo };
+export type { RemoteLogoProps };

package/dist/components/NavBar.d.cts

@@ -32,4 +32,5 @@ interface NavProps {
  */
 declare function Navbar({ links, logo }: NavProps): React.JSX.Element;
 
-export { type NavProps, Navbar, type SocialLink };
+export { Navbar };
+export type { NavProps, SocialLink };

package/dist/components/NavBar.d.ts

@@ -32,4 +32,5 @@ interface NavProps {
  */
 declare function Navbar({ links, logo }: NavProps): React.JSX.Element;
 
-export { type NavProps, Navbar, type SocialLink };
+export { Navbar };
+export type { NavProps, SocialLink };

package/dist/components/Orb.d.cts

@@ -26,4 +26,5 @@ interface OrbProps extends React__default.HTMLAttributes<HTMLDivElement> {
  */
 declare const Orb: React__default.ForwardRefExoticComponent<OrbProps & React__default.RefAttributes<HTMLDivElement>>;
 
-export { Orb, type OrbProps, type PackageType };
+export { Orb };
+export type { OrbProps, PackageType };

package/dist/components/Orb.d.ts

@@ -26,4 +26,5 @@ interface OrbProps extends React__default.HTMLAttributes<HTMLDivElement> {
  */
 declare const Orb: React__default.ForwardRefExoticComponent<OrbProps & React__default.RefAttributes<HTMLDivElement>>;
 
-export { Orb, type OrbProps, type PackageType };
+export { Orb };
+export type { OrbProps, PackageType };

package/dist/components/PolicyDocument.d.cts

@@ -54,4 +54,5 @@ interface PolicyDocumentProps {
  */
 declare function PolicyDocument({ slug, content, source, labels, className, classNames, }: PolicyDocumentProps): React.JSX.Element;
 
-export { PolicyDocument, type PolicyDocumentProps };
+export { PolicyDocument };
+export type { PolicyDocumentProps };

package/dist/components/PolicyDocument.d.ts

@@ -54,4 +54,5 @@ interface PolicyDocumentProps {
  */
 declare function PolicyDocument({ slug, content, source, labels, className, classNames, }: PolicyDocumentProps): React.JSX.Element;
 
-export { PolicyDocument, type PolicyDocumentProps };
+export { PolicyDocument };
+export type { PolicyDocumentProps };

package/dist/components/ThemeSwitcher.d.cts

@@ -19,4 +19,5 @@ interface ThemeSwitcherProps {
  */
 declare function ThemeSwitcher({ theme, onToggle }: ThemeSwitcherProps): React.JSX.Element;
 
-export { ThemeSwitcher, type ThemeSwitcherProps };
+export { ThemeSwitcher };
+export type { ThemeSwitcherProps };

package/dist/components/ThemeSwitcher.d.ts

@@ -19,4 +19,5 @@ interface ThemeSwitcherProps {
  */
 declare function ThemeSwitcher({ theme, onToggle }: ThemeSwitcherProps): React.JSX.Element;
 
-export { ThemeSwitcher, type ThemeSwitcherProps };
+export { ThemeSwitcher };
+export type { ThemeSwitcherProps };

package/dist/index.cjs

@@ -42,6 +42,7 @@ __reExport(index_exports, require("./components/PolicyDocument"), module.exports
 var import_StarryBackground = __toESM(require("./components/StarryBackground"), 1);
 __reExport(index_exports, require("./components/ThemeSwitcher"), module.exports);
 __reExport(index_exports, require("./policies"), module.exports);
+__reExport(index_exports, require("./preferences"), module.exports);
 __reExport(index_exports, require("./utils"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -54,5 +55,6 @@ __reExport(index_exports, require("./utils"), module.exports);
   ...require("./components/PolicyDocument"),
   ...require("./components/ThemeSwitcher"),
   ...require("./policies"),
+  ...require("./preferences"),
   ...require("./utils")
 });

package/dist/index.d.cts

@@ -7,5 +7,6 @@ export { PolicyDocument, PolicyDocumentProps } from './components/PolicyDocument
 export { default as StarryBackground } from './components/StarryBackground.cjs';
 export { ThemeSwitcher, ThemeSwitcherProps } from './components/ThemeSwitcher.cjs';
 export { POLICIES_INDEX_URL, POLICY_SITE_URL, POLICY_SOURCE, Policy, PolicyContent, PolicySection, PolicySlug, footerPolicies, getPolicyFileUrl, getPolicyPageUrl, loadPolicy, policies, publishedPolicies } from './policies.cjs';
+export { PREFERENCE_DAYS, PreferenceExpiry, expireStoredPreferences } from './preferences.cjs';
 export { baseFooterLinks, baseNavLinks } from './utils.cjs';
 import 'react';

package/dist/index.d.ts

@@ -7,5 +7,6 @@ export { PolicyDocument, PolicyDocumentProps } from './components/PolicyDocument
 export { default as StarryBackground } from './components/StarryBackground.js';
 export { ThemeSwitcher, ThemeSwitcherProps } from './components/ThemeSwitcher.js';
 export { POLICIES_INDEX_URL, POLICY_SITE_URL, POLICY_SOURCE, Policy, PolicyContent, PolicySection, PolicySlug, footerPolicies, getPolicyFileUrl, getPolicyPageUrl, loadPolicy, policies, publishedPolicies } from './policies.js';
+export { PREFERENCE_DAYS, PreferenceExpiry, expireStoredPreferences } from './preferences.js';
 export { baseFooterLinks, baseNavLinks } from './utils.js';
 import 'react';

package/dist/index.js

@@ -7,6 +7,7 @@ export * from "./components/PolicyDocument";
 import { default as default3 } from "./components/StarryBackground";
 export * from "./components/ThemeSwitcher";
 export * from "./policies";
+export * from "./preferences";
 export * from "./utils";
 export {
   default2 as NoSSR,

package/dist/policies.d.cts

@@ -85,4 +85,5 @@ declare function loadPolicy(slug: PolicySlug, options?: {
     revalidate?: number | false;
 }): Promise<PolicyContent>;
 
-export { POLICIES_INDEX_URL, POLICY_SITE_URL, POLICY_SOURCE, type Policy, type PolicyContent, type PolicySection, type PolicySlug, footerPolicies, getPolicyFileUrl, getPolicyPageUrl, loadPolicy, policies, publishedPolicies };
+export { POLICIES_INDEX_URL, POLICY_SITE_URL, POLICY_SOURCE, footerPolicies, getPolicyFileUrl, getPolicyPageUrl, loadPolicy, policies, publishedPolicies };
+export type { Policy, PolicyContent, PolicySection, PolicySlug };

package/dist/policies.d.ts

@@ -85,4 +85,5 @@ declare function loadPolicy(slug: PolicySlug, options?: {
     revalidate?: number | false;
 }): Promise<PolicyContent>;
 
-export { POLICIES_INDEX_URL, POLICY_SITE_URL, POLICY_SOURCE, type Policy, type PolicyContent, type PolicySection, type PolicySlug, footerPolicies, getPolicyFileUrl, getPolicyPageUrl, loadPolicy, policies, publishedPolicies };
+export { POLICIES_INDEX_URL, POLICY_SITE_URL, POLICY_SOURCE, footerPolicies, getPolicyFileUrl, getPolicyPageUrl, loadPolicy, policies, publishedPolicies };
+export type { Policy, PolicyContent, PolicySection, PolicySlug };

package/dist/preferences.cjs

@@ -0,0 +1,55 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var preferences_exports = {};
+__export(preferences_exports, {
+  PREFERENCE_DAYS: () => PREFERENCE_DAYS,
+  PreferenceExpiry: () => PreferenceExpiry,
+  expireStoredPreferences: () => expireStoredPreferences
+});
+module.exports = __toCommonJS(preferences_exports);
+var import_jsx_runtime = require("react/jsx-runtime");
+const PREFERENCE_DAYS = 30;
+function expireStoredPreferences(storage, proto, keys, ms, now) {
+  try {
+    for (const key of keys) {
+      const expiresAt = Number(storage.getItem(key + ":expires"));
+      if (!expiresAt || expiresAt <= now) {
+        storage.removeItem(key);
+        storage.removeItem(key + ":expires");
+      }
+    }
+    const setItem = proto.setItem;
+    proto.setItem = function(key, value) {
+      setItem.call(this, key, value);
+      if (this === storage && keys.indexOf(key) >= 0) setItem.call(this, key + ":expires", String(Date.now() + ms));
+    };
+  } catch {
+  }
+}
+function PreferenceExpiry({ keys = ["theme"] }) {
+  const ms = PREFERENCE_DAYS * 864e5;
+  const code = `(${expireStoredPreferences.toString()})(window.localStorage, Storage.prototype, ${JSON.stringify(keys)}, ${ms}, Date.now())`;
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("script", { dangerouslySetInnerHTML: { __html: code } });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PREFERENCE_DAYS,
+  PreferenceExpiry,
+  expireStoredPreferences
+});

package/dist/preferences.d.cts

@@ -0,0 +1,28 @@
+import * as React from 'react';
+
+/** How long the TUWA sites keep an interface setting after it is chosen (Cookie Policy). */
+declare const PREFERENCE_DAYS = 30;
+/**
+ * Forgets the given Local Storage values once their 30 days have passed (or when they were saved before values had an
+ * expiry), then dates every later write of those keys: `<key>:expires` holds the time in epoch milliseconds. It runs
+ * inline in the page head, before next-themes or Nextra read the values, so it works whatever library writes them;
+ * it is serialised with `toString()`, so it uses only its arguments.
+ *
+ * @param storage - `window.localStorage`.
+ * @param proto - `Storage.prototype`, whose `setItem` is wrapped to date the writes of `keys`.
+ * @param keys - The keys of the interface settings, such as `theme`.
+ * @param ms - How long a value is kept after it is written.
+ * @param now - The current time.
+ */
+declare function expireStoredPreferences(storage: Storage, proto: Pick<Storage, 'setItem'>, keys: string[], ms: number, now: number): void;
+/**
+ * The inline script of {@link expireStoredPreferences}, for the `<head>` of a site's root layout, before the theme
+ * script of next-themes.
+ *
+ * @param props.keys - The Local Storage keys to keep for {@link PREFERENCE_DAYS} days; `theme` by default.
+ */
+declare function PreferenceExpiry({ keys }: {
+    keys?: string[];
+}): React.JSX.Element;
+
+export { PREFERENCE_DAYS, PreferenceExpiry, expireStoredPreferences };

package/dist/preferences.d.ts

@@ -0,0 +1,28 @@
+import * as React from 'react';
+
+/** How long the TUWA sites keep an interface setting after it is chosen (Cookie Policy). */
+declare const PREFERENCE_DAYS = 30;
+/**
+ * Forgets the given Local Storage values once their 30 days have passed (or when they were saved before values had an
+ * expiry), then dates every later write of those keys: `<key>:expires` holds the time in epoch milliseconds. It runs
+ * inline in the page head, before next-themes or Nextra read the values, so it works whatever library writes them;
+ * it is serialised with `toString()`, so it uses only its arguments.
+ *
+ * @param storage - `window.localStorage`.
+ * @param proto - `Storage.prototype`, whose `setItem` is wrapped to date the writes of `keys`.
+ * @param keys - The keys of the interface settings, such as `theme`.
+ * @param ms - How long a value is kept after it is written.
+ * @param now - The current time.
+ */
+declare function expireStoredPreferences(storage: Storage, proto: Pick<Storage, 'setItem'>, keys: string[], ms: number, now: number): void;
+/**
+ * The inline script of {@link expireStoredPreferences}, for the `<head>` of a site's root layout, before the theme
+ * script of next-themes.
+ *
+ * @param props.keys - The Local Storage keys to keep for {@link PREFERENCE_DAYS} days; `theme` by default.
+ */
+declare function PreferenceExpiry({ keys }: {
+    keys?: string[];
+}): React.JSX.Element;
+
+export { PREFERENCE_DAYS, PreferenceExpiry, expireStoredPreferences };

package/dist/preferences.js

@@ -0,0 +1,29 @@
+import { jsx } from "react/jsx-runtime";
+const PREFERENCE_DAYS = 30;
+function expireStoredPreferences(storage, proto, keys, ms, now) {
+  try {
+    for (const key of keys) {
+      const expiresAt = Number(storage.getItem(key + ":expires"));
+      if (!expiresAt || expiresAt <= now) {
+        storage.removeItem(key);
+        storage.removeItem(key + ":expires");
+      }
+    }
+    const setItem = proto.setItem;
+    proto.setItem = function(key, value) {
+      setItem.call(this, key, value);
+      if (this === storage && keys.indexOf(key) >= 0) setItem.call(this, key + ":expires", String(Date.now() + ms));
+    };
+  } catch {
+  }
+}
+function PreferenceExpiry({ keys = ["theme"] }) {
+  const ms = PREFERENCE_DAYS * 864e5;
+  const code = `(${expireStoredPreferences.toString()})(window.localStorage, Storage.prototype, ${JSON.stringify(keys)}, ${ms}, Date.now())`;
+  return /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: code } });
+}
+export {
+  PREFERENCE_DAYS,
+  PreferenceExpiry,
+  expireStoredPreferences
+};

package/dist/searchIndex.cjs

@@ -0,0 +1,77 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var searchIndex_exports = {};
+__export(searchIndex_exports, {
+  buildSearchIndex: () => buildSearchIndex,
+  findPrerenderedPages: () => findPrerenderedPages
+});
+module.exports = __toCommonJS(searchIndex_exports);
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+var import_node_url = require("node:url");
+const directories = (dir) => (0, import_node_fs.existsSync)(dir) ? (0, import_node_fs.readdirSync)(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => (0, import_node_path.join)(dir, entry.name)) : [];
+const htmlFiles = (root) => (0, import_node_fs.existsSync)(root) ? (0, import_node_fs.readdirSync)(root, { recursive: true, encoding: "utf8" }).filter((path) => path.endsWith(".html")).map((path) => ({ file: (0, import_node_path.join)(root, path), sourcePath: path.split(import_node_path.sep).join("/") })) : [];
+function findPrerenderedPages(serverDir) {
+  const roots = [
+    (0, import_node_path.join)(serverDir, "app"),
+    ...directories((0, import_node_path.join)(serverDir, "route-cache")).flatMap(directories).map((route) => (0, import_node_path.join)(route, "$"))
+  ];
+  return roots.flatMap(htmlFiles).sort((a, b) => a.sourcePath < b.sourcePath ? -1 : 1);
+}
+async function loadPagefind(cwd) {
+  for (let dir = (0, import_node_path.resolve)(cwd); ; dir = (0, import_node_path.dirname)(dir)) {
+    const manifest = (0, import_node_path.join)(dir, "node_modules", "pagefind", "package.json");
+    if ((0, import_node_fs.existsSync)(manifest)) {
+      const pkg = JSON.parse((0, import_node_fs.readFileSync)(manifest, "utf8"));
+      const entry = pkg.exports?.["."]?.import ?? pkg.main ?? "lib/index.js";
+      return await import((0, import_node_url.pathToFileURL)((0, import_node_path.join)((0, import_node_path.dirname)(manifest), entry)).href);
+    }
+    if ((0, import_node_path.dirname)(dir) === dir) throw new Error("pagefind is not installed: add it to the dependencies of the site");
+  }
+}
+async function buildSearchIndex({
+  serverDir = ".next/server",
+  outputPath = "public/_pagefind",
+  cwd = process.cwd()
+} = {}) {
+  const pages = findPrerenderedPages((0, import_node_path.resolve)(cwd, serverDir));
+  if (!pages.length) throw new Error(`Found no prerendered pages in ${serverDir}: run next build first`);
+  const pagefind = await loadPagefind(cwd);
+  try {
+    const { index, errors } = await pagefind.createIndex();
+    if (!index) throw new Error(`Pagefind: ${errors.join("; ")}`);
+    const urls = [];
+    for (const page of pages) {
+      const added = await index.addHTMLFile({ sourcePath: page.sourcePath, content: (0, import_node_fs.readFileSync)(page.file, "utf8") });
+      if (added.errors.length || !added.file)
+        throw new Error(`Pagefind, ${page.sourcePath}: ${added.errors.join("; ")}`);
+      urls.push(added.file.url);
+    }
+    const written = await index.writeFiles({ outputPath: (0, import_node_path.resolve)(cwd, outputPath) });
+    if (written.errors.length) throw new Error(`Pagefind: ${written.errors.join("; ")}`);
+    return { urls };
+  } finally {
+    await pagefind.close();
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildSearchIndex,
+  findPrerenderedPages
+});

package/dist/searchIndex.d.cts

@@ -0,0 +1,40 @@
+/** A page that `next build` prerendered: its HTML file and the path from which Pagefind derives its URL. */
+type PrerenderedPage = {
+    /** The HTML file in `.next/server`. */
+    file: string;
+    /** The path of the page in the site, such as `packages/orbit-core.html` (URL `/packages/orbit-core.html`). */
+    sourcePath: string;
+};
+/**
+ * Lists the pages that `next build` prerendered as HTML. A build without an adapter keeps them in
+ * `<serverDir>/app/<path>.html`; a build with an adapter (Next 16.3.8 and later on Vercel) keeps them in
+ * `<serverDir>/route-cache/<kind>/<hash of the route>/$/<path>.html`. Both give the same paths.
+ *
+ * @param serverDir - The `.next/server` directory of the site.
+ * @returns The pages, sorted by path.
+ */
+declare function findPrerenderedPages(serverDir: string): PrerenderedPage[];
+/**
+ * Builds the Pagefind index of a documentation site from the pages that `next build` prerendered, in either layout
+ * of {@link findPrerenderedPages}, with the URLs `pagefind --site .next/server/app` gave them. Nextra's search loads it
+ * from `/_pagefind/pagefind.js`.
+ *
+ * Side effects: starts the Pagefind binary of the site's `pagefind` package and writes the index to `outputPath`.
+ *
+ * @param options - Where to read and write, relative to `cwd`.
+ * @param options.serverDir - The `.next/server` directory. Default `.next/server`.
+ * @param options.outputPath - Where the index is written. Default `public/_pagefind`.
+ * @param options.cwd - The directory of the site, where `pagefind` is installed. Default the current directory.
+ * @returns The URLs of the indexed pages.
+ * @throws When the build has no prerendered pages, or when Pagefind is missing or reports an error.
+ */
+declare function buildSearchIndex({ serverDir, outputPath, cwd, }?: {
+    serverDir?: string;
+    outputPath?: string;
+    cwd?: string;
+}): Promise<{
+    urls: string[];
+}>;
+
+export { buildSearchIndex, findPrerenderedPages };
+export type { PrerenderedPage };

package/dist/searchIndex.d.ts

@@ -0,0 +1,40 @@
+/** A page that `next build` prerendered: its HTML file and the path from which Pagefind derives its URL. */
+type PrerenderedPage = {
+    /** The HTML file in `.next/server`. */
+    file: string;
+    /** The path of the page in the site, such as `packages/orbit-core.html` (URL `/packages/orbit-core.html`). */
+    sourcePath: string;
+};
+/**
+ * Lists the pages that `next build` prerendered as HTML. A build without an adapter keeps them in
+ * `<serverDir>/app/<path>.html`; a build with an adapter (Next 16.3.8 and later on Vercel) keeps them in
+ * `<serverDir>/route-cache/<kind>/<hash of the route>/$/<path>.html`. Both give the same paths.
+ *
+ * @param serverDir - The `.next/server` directory of the site.
+ * @returns The pages, sorted by path.
+ */
+declare function findPrerenderedPages(serverDir: string): PrerenderedPage[];
+/**
+ * Builds the Pagefind index of a documentation site from the pages that `next build` prerendered, in either layout
+ * of {@link findPrerenderedPages}, with the URLs `pagefind --site .next/server/app` gave them. Nextra's search loads it
+ * from `/_pagefind/pagefind.js`.
+ *
+ * Side effects: starts the Pagefind binary of the site's `pagefind` package and writes the index to `outputPath`.
+ *
+ * @param options - Where to read and write, relative to `cwd`.
+ * @param options.serverDir - The `.next/server` directory. Default `.next/server`.
+ * @param options.outputPath - Where the index is written. Default `public/_pagefind`.
+ * @param options.cwd - The directory of the site, where `pagefind` is installed. Default the current directory.
+ * @returns The URLs of the indexed pages.
+ * @throws When the build has no prerendered pages, or when Pagefind is missing or reports an error.
+ */
+declare function buildSearchIndex({ serverDir, outputPath, cwd, }?: {
+    serverDir?: string;
+    outputPath?: string;
+    cwd?: string;
+}): Promise<{
+    urls: string[];
+}>;
+
+export { buildSearchIndex, findPrerenderedPages };
+export type { PrerenderedPage };

package/dist/searchIndex.js

@@ -0,0 +1,52 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+const directories = (dir) => existsSync(dir) ? readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => join(dir, entry.name)) : [];
+const htmlFiles = (root) => existsSync(root) ? readdirSync(root, { recursive: true, encoding: "utf8" }).filter((path) => path.endsWith(".html")).map((path) => ({ file: join(root, path), sourcePath: path.split(sep).join("/") })) : [];
+function findPrerenderedPages(serverDir) {
+  const roots = [
+    join(serverDir, "app"),
+    ...directories(join(serverDir, "route-cache")).flatMap(directories).map((route) => join(route, "$"))
+  ];
+  return roots.flatMap(htmlFiles).sort((a, b) => a.sourcePath < b.sourcePath ? -1 : 1);
+}
+async function loadPagefind(cwd) {
+  for (let dir = resolve(cwd); ; dir = dirname(dir)) {
+    const manifest = join(dir, "node_modules", "pagefind", "package.json");
+    if (existsSync(manifest)) {
+      const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+      const entry = pkg.exports?.["."]?.import ?? pkg.main ?? "lib/index.js";
+      return await import(pathToFileURL(join(dirname(manifest), entry)).href);
+    }
+    if (dirname(dir) === dir) throw new Error("pagefind is not installed: add it to the dependencies of the site");
+  }
+}
+async function buildSearchIndex({
+  serverDir = ".next/server",
+  outputPath = "public/_pagefind",
+  cwd = process.cwd()
+} = {}) {
+  const pages = findPrerenderedPages(resolve(cwd, serverDir));
+  if (!pages.length) throw new Error(`Found no prerendered pages in ${serverDir}: run next build first`);
+  const pagefind = await loadPagefind(cwd);
+  try {
+    const { index, errors } = await pagefind.createIndex();
+    if (!index) throw new Error(`Pagefind: ${errors.join("; ")}`);
+    const urls = [];
+    for (const page of pages) {
+      const added = await index.addHTMLFile({ sourcePath: page.sourcePath, content: readFileSync(page.file, "utf8") });
+      if (added.errors.length || !added.file)
+        throw new Error(`Pagefind, ${page.sourcePath}: ${added.errors.join("; ")}`);
+      urls.push(added.file.url);
+    }
+    const written = await index.writeFiles({ outputPath: resolve(cwd, outputPath) });
+    if (written.errors.length) throw new Error(`Pagefind: ${written.errors.join("; ")}`);
+    return { urls };
+  } finally {
+    await pagefind.close();
+  }
+}
+export {
+  buildSearchIndex,
+  findPrerenderedPages
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuwaio/docs-ui",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "private": false,
   "author": "Oleksandr Tkach",
   "license": "Apache-2.0",
@@ -8,12 +8,15 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "tuwa-docs-search-index": "./bin/search-index.js"
+  },
   "type": "module",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.cjs"
     },
     "./policies": {
       "types": "./dist/policies.d.ts",
@@ -27,6 +30,7 @@
     "access": "public"
   },
   "files": [
+    "bin",
     "dist",
     "socket.json"
   ],
@@ -72,17 +76,17 @@
     "@heroicons/react": "^2.2.0",
     "@tailwindcss/postcss": "^4.3.3",
     "@tailwindcss/vite": "^4.3.3",
-    "@types/node": "^26",
+    "@types/node": "^26.6.5",
     "@types/react": "^19.3.0",
     "autoprefixer": "^10.6.1",
-    "next": "16.3.7",
+    "next": "16.4.1",
     "nextra": "^4.6.1",
     "nextra-theme-docs": "^4.6.1",
-    "postcss": "^8.5.28",
+    "postcss": "^8.5.30",
     "postcss-cli": "^12.0.0",
-    "react": "^19.3.0",
+    "react": "^19.3.1",
     "tailwindcss": "^4.3.3",
-    "tsup": "^8.5.1",
+    "tsup": "^9.0.0",
     "typescript": "6.0.3"
   },
   "scripts": {