@integr8-media/config 1.0.0 → 1.2.0

package/dist/registrySite.d.mts

@@ -0,0 +1,959 @@
+import { n as ConfigErrorCode, t as ConfigError } from "./configError-DPT5pJ9Z.mjs";
+import { Server } from "node:http";
+/** A file of a registry item. */
+interface RegistryFile {
+  path: string;
+  type?: string | undefined;
+  /** Where the file lands in a shadcn project. */
+  target?: string | undefined;
+  /** The file's text. Left out of `registry.json`, present in `<name>.json`. */
+  content?: string | undefined;
+}
+/** An entry of `registry.json`. */
+interface RegistryIndexItem {
+  name: string;
+  /** For example `registry:ui`. */
+  type: string;
+  title?: string | undefined;
+  description?: string | undefined;
+  categories?: string[] | undefined;
+}
+/** `registry.json`. */
+interface RegistryIndex {
+  /** The package name. */
+  name: string;
+  items: RegistryIndexItem[];
+}
+/** A full item (`<name>.json`), with file contents. */
+interface RegistryItem extends RegistryIndexItem {
+  dependencies?: string[] | undefined;
+  /** Full URLs of the items it needs. */
+  registryDependencies?: string[] | undefined;
+  files?: RegistryFile[] | undefined;
+  /** Theme tokens added to the project's CSS. */
+  cssVars?: {
+    light?: Record<string, string>;
+    dark?: Record<string, string>;
+  } | undefined;
+  /** Rules and at-rules added to the project's CSS. */
+  css?: Record<string, unknown> | undefined;
+}
+/** An `[id, label]` pair, for categories and preview themes. */
+type SiteEntry = readonly [id: string, label: string];
+/** Where the site's fonts come from. See {@link RegistrySiteConfig.fonts}. */
+type SiteFonts = "copy-from-ui" | "build" | false;
+/** Texts and links that make the site look like this package's. */
+interface SiteBrand {
+  /** Product name, for example `Integr8 Window Manager`. Used in titles and labels. Required. */
+  name: string;
+  /**
+   * Shown after `integr8/` in the header, for example `window-manager`. Defaults to the name
+   * without a leading "Integr8", in kebab-case.
+   */
+  slug?: string | undefined;
+  /** Two letters in the header badge. Defaults to `i8`. */
+  mark?: string | undefined;
+  /** Small text above the hero title; the version is added (`Window manager · v1.0.0`). Defaults to `Registry`. */
+  eyebrow?: string | undefined;
+  /** Hero title. Defaults to `name`. */
+  heroTitle?: string | undefined;
+  /** The last words of the hero title, in the brand gradient (for example `inside your React app.`). */
+  heroAccent?: string | undefined;
+  /** Text under the hero title. Defaults to the `description` of `package.json`. */
+  lead?: string | undefined;
+  /** The page `<title>` of the landing page. Defaults to `name`. */
+  title?: string | undefined;
+  /** The meta description. Defaults to the `description` of `package.json`. */
+  description?: string | undefined;
+  /**
+   * First part of the footer. `{packageName}` and `{version}` are filled in.
+   * Defaults to `{packageName} · v{version}`.
+   */
+  footer?: string | undefined;
+  /**
+   * Link to the source repository. Defaults to `https://github.com/$GITHUB_REPOSITORY`, else
+   * the `repository` of `package.json`.
+   */
+  repositoryUrl?: string | undefined;
+  /** Add a "Playground" link to the header (it opens the Ladle playground). Defaults to `false`. */
+  playgroundLink?: boolean | undefined;
+  /** Extra numbers in the hero, after the component count (for example `{ value: '5', label: 'themes' }`). */
+  extraStats?: readonly {
+    value: string;
+    label: string;
+  }[] | undefined;
+  /** Command in the hero. Defaults to the command of the last setup step. */
+  heroCommand?: string | undefined;
+}
+/** One numbered step in "Get started". */
+interface SiteSetupStep {
+  title: string;
+  /** Inline Markdown (`code`, **bold**, [links](https://x.dev)). */
+  text?: string | undefined;
+  /** The copyable command. */
+  command: string;
+}
+/** A card with a code sample under the steps. */
+interface SiteSetupExtra {
+  title: string;
+  /** Inline Markdown. */
+  text?: string | undefined;
+  code: string;
+  /** Label above the code, for example a file name. */
+  caption?: string | undefined;
+}
+/**
+ * The "Get started" section. Texts, commands and code may use `{registryUrl}`,
+ * `{uiRegistryUrl}`, `{version}` and `{packageName}`; any other `{...}` stays as written
+ * (so `{name}` in a `components.json` sample is kept).
+ */
+interface SiteSetup {
+  /** Heading before the accent. Defaults to `<Three> commands to` (from the step count). */
+  title?: string | undefined;
+  /** Gradient part of the heading. Defaults to `your first screen.` */
+  accent?: string | undefined;
+  /** Text under the heading. */
+  lead?: string | undefined;
+  /**
+   * The steps. Defaults to: set up shadcn, add the ui theme (when `ui` is set), add the first
+   * item of the registry.
+   */
+  steps?: readonly SiteSetupStep[] | undefined;
+  /** Cards after the steps, for example an app example. */
+  extras?: readonly SiteSetupExtra[] | undefined;
+  /**
+   * The registry alias for `components.json`, for example `@integr8-wm`. Defaults to `@integr8`,
+   * or `@integr8-<slug>` when `ui` is set (the ui registry then has `@integr8`).
+   */
+  namespace?: string | undefined;
+  /** Add the "Shorter names" card (the `components.json` registry setting). Defaults to `true`. */
+  shortNames?: boolean | undefined;
+}
+/** Longer texts of the landing page. Each has a default. */
+interface SiteCopy {
+  /** Text under "See it before you copy it." */
+  previewLead?: string | undefined;
+  /** Text under "Everything in the kit." */
+  componentsLead?: string | undefined;
+}
+/** The ui registry, when the items depend on it. Leave `ui` out in the ui package itself. */
+interface SiteUi {
+  /** Where the ui registry JSON files are served, for example `https://host/integr8-ui/r`. */
+  registryUrl: string;
+  /** Where the ui item pages are. Defaults to the registry URL without `/r`, plus `/components/`. */
+  docsUrl?: string | undefined;
+  /** The ui package name, for the fonts copy. Defaults to `@integr8-media/ui`. */
+  packageName?: string | undefined;
+}
+/**
+ * Which Ladle stories show which item: a map of item name to parts of story ids (Ladle ids look
+ * like `components--window-default`; a story matches when its id contains a part), or a function
+ * that returns the parts for an item. Items without parts have no live preview.
+ */
+type SiteStories = Readonly<Record<string, readonly string[]>> | ((itemName: string) => readonly string[] | undefined);
+/** Settings of the bundle-size breakdown (`integr8-registry-site size`). */
+interface SiteBundleSizes {
+  /** The built entry to measure, relative to the repo root. Defaults to `dist/index.mjs`. */
+  entry?: string | undefined;
+  /** Label for this package's own code in the tables. Defaults to `<package name> (dist)`. */
+  ownCodeLabel?: string | undefined;
+  /** Packages the app provides, left out of the measure. Defaults to React and React DOM. */
+  external?: readonly string[] | undefined;
+}
+/** The commands `integr8-registry-site build` runs before it renders the pages. */
+interface SiteCommands {
+  /** Builds fonts (needed with `fonts: 'build'`), for example `node scripts/buildAssets.mjs`. Runs first. */
+  assets?: string | undefined;
+  /** Builds the registry JSON into `dist/registry/`. Defaults to `node scripts/buildRegistry.mjs`. */
+  registry?: string | undefined;
+}
+/**
+ * The per-repo configuration of the registry site: the file `registry/site.config.mjs`.
+ * Only `brand.name` is required.
+ *
+ * @example
+ * ```js
+ * // registry/site.config.mjs
+ * import { defineRegistrySite } from '@integr8-media/config/registry-site';
+ *
+ * export default defineRegistrySite({
+ *   brand: { name: 'Integr8 Window Manager', slug: 'window-manager' },
+ *   categories: [['shell', 'Shell'], ['window', 'Windows']],
+ *   ui: { registryUrl: 'https://minalouisleon.github.io/integr8-ui/r' },
+ * });
+ * ```
+ */
+interface RegistrySiteConfig {
+  /** Names, texts and links. */
+  brand: SiteBrand;
+  /**
+   * Item groups in page order, as `[id, label]` pairs matched against each item's first registry
+   * category. Items in no group go last under "Other". Defaults to the categories found in the
+   * registry, in order of first appearance.
+   */
+  categories?: readonly SiteEntry[] | undefined;
+  /** Which stories preview which item. Defaults to the stories whose id starts with `<item>--`. */
+  stories?: SiteStories | undefined;
+  /**
+   * The story shown first in the landing page's live preview: an item name (its first story) or
+   * a story id. Defaults to the first story.
+   */
+  defaultStory?: string | undefined;
+  /** The ui registry. Leave out in the ui package itself. */
+  ui?: SiteUi | undefined;
+  /**
+   * Fonts of the site: `'copy-from-ui'` copies `dist/fonts.css` and `dist/fonts/` from the
+   * installed ui package (needs `ui`), `'build'` copies the ones this repo built into `dist/`,
+   * `false` uses system fonts. Defaults to `'copy-from-ui'` with `ui`, else `false`.
+   */
+  fonts?: SiteFonts | undefined;
+  /** The "Get started" section. */
+  setup?: SiteSetup | undefined;
+  /** Longer landing page texts. */
+  copy?: SiteCopy | undefined;
+  /** Themes the live preview can switch between, as `[id, label]` pairs. Leave out for no switcher. */
+  previewThemes?: readonly SiteEntry[] | undefined;
+  /**
+   * The "add the theme first" note on item pages: `{ item }` names the theme item, `skip` lists
+   * items without the note. Defaults to the ui theme when `ui` is set, else no note.
+   */
+  themeNote?: {
+    item: string;
+    skip?: readonly string[] | undefined;
+  } | false | undefined;
+  /** Bundle-size breakdown for `integr8-registry-site size`. Off unless set. */
+  bundleSizes?: SiteBundleSizes | false | undefined;
+  /** Build steps. */
+  commands?: SiteCommands | undefined;
+  /**
+   * Where the registry JSON files are served; `{name}` and `{version}` are filled in. The
+   * `REGISTRY_BASE_URL` variable wins. Defaults to the GitHub Pages URL of the repository.
+   */
+  registryUrl?: string | undefined;
+  /** Build the Ladle playground and embed it. Defaults to `true`. */
+  playground?: boolean | undefined;
+}
+/** The facts of `package.json` the site needs. */
+interface SitePackage {
+  name: string;
+  version: string;
+  description?: string | undefined;
+  repository?: string | {
+    url?: string | undefined;
+  } | undefined;
+}
+/** Environment variables the site reads (`GITHUB_REPOSITORY`, `REGISTRY_BASE_URL`). */
+type SiteEnv = Readonly<Record<string, string | undefined>>;
+/** A {@link RegistrySiteConfig} with every default filled in. */
+interface ResolvedSiteConfig {
+  brand: {
+    name: string;
+    slug: string;
+    mark: string;
+    eyebrow: string;
+    heroTitle: string;
+    heroAccent: string;
+    lead: string;
+    title: string;
+    description: string;
+    footer: string;
+    repositoryUrl: string | undefined;
+    playgroundLink: boolean;
+    extraStats: readonly {
+      value: string;
+      label: string;
+    }[];
+    heroCommand: string | undefined;
+  };
+  categories: readonly SiteEntry[] | undefined;
+  stories: SiteStories | undefined;
+  defaultStory: string | undefined;
+  ui: {
+    registryUrl: string;
+    docsUrl: string;
+    packageName: string;
+  } | undefined;
+  fonts: SiteFonts;
+  setup: {
+    title: string | undefined;
+    accent: string;
+    lead: string;
+    steps: readonly SiteSetupStep[] | undefined;
+    extras: readonly SiteSetupExtra[];
+    namespace: string;
+    shortNames: boolean;
+  };
+  copy: {
+    previewLead: string | undefined;
+    componentsLead: string;
+  };
+  previewThemes: readonly SiteEntry[];
+  themeNote: {
+    item: string;
+    skip: readonly string[];
+    external: boolean;
+  } | undefined;
+  bundleSizes: {
+    entry: string;
+    ownCodeLabel: string;
+    external: readonly string[];
+  } | undefined;
+  commands: {
+    assets: string | undefined;
+    registry: string;
+  };
+  registryUrl: string | undefined;
+  playground: boolean;
+}
+/**
+ * Checks a site config and returns it. Use it in `registry/site.config.mjs` to get early,
+ * readable errors and editor hints.
+ *
+ * @param config - The config object.
+ * @returns The same config, typed.
+ * @throws {@link ConfigError} with code `INVALID_OPTION`, naming the option and what is wrong
+ * (a missing `brand.name`, an unknown option, `fonts: 'copy-from-ui'` without `ui`, a repeated
+ * category id, and so on).
+ *
+ * @example
+ * ```js
+ * export default defineRegistrySite({ brand: { name: 'Integr8 Forms' } });
+ * ```
+ */
+export declare function defineRegistrySite(config: RegistrySiteConfig): RegistrySiteConfig;
+/**
+ * The URL the registry JSON files are served from, without a trailing slash. The
+ * `REGISTRY_BASE_URL` variable wins over `registryUrl` in the config; without either, it is the
+ * GitHub Pages URL of the `repository` in `package.json`.
+ *
+ * @param configured - `registryUrl` from the site config.
+ * @param pkg - Name, version and repository of the package.
+ * @param env - Environment variables.
+ * @returns The folder URL, for example `https://owner.github.io/repo/r`.
+ * @throws {@link ConfigError} with code `INVALID_OPTION` when none of the three gives a URL.
+ */
+export declare function resolveRegistryUrl(configured: string | undefined, pkg: SitePackage, env: SiteEnv): string;
+/**
+ * The folder where the ui item pages are: the ui registry URL without a trailing `/r`, then
+ * `components/`.
+ *
+ * @param registryUrl - The ui registry URL.
+ * @returns A URL ending with `/`.
+ */
+export declare function uiDocsUrlOf(registryUrl: string): string;
+/**
+ * Validates a site config and fills in every default.
+ *
+ * @param config - The repo's config.
+ * @param context - `package.json` facts and the environment (default: the process environment).
+ * @returns The full config the renderers use.
+ * @throws {@link ConfigError} with code `INVALID_OPTION` for bad input.
+ */
+export declare function resolveSiteConfig(config: RegistrySiteConfig, context: {
+  pkg: SitePackage;
+  env?: SiteEnv | undefined;
+}): ResolvedSiteConfig;
+/** A Ladle story as shown on a page. */
+interface LadleStory {
+  id: string;
+  name: string;
+}
+/** The `stories` of Ladle's `meta.json`: id → details. */
+type LadleStoryMap = Readonly<Record<string, {
+  name?: string | undefined;
+}>>;
+/**
+ * The stories of a parsed Ladle `meta.json`. Anything that is not a story map gives `{}`.
+ *
+ * @param meta - The parsed `playground/dist/meta.json`.
+ * @returns Story id → details.
+ */
+export declare function readLadleStories(meta: unknown): LadleStoryMap;
+/**
+ * The Ladle stories that preview an item.
+ *
+ * - `stories` not set: the stories whose id starts with `<item>--` (the id of `Button.stories.tsx`
+ *   starts with `button--`).
+ * - a map or a function: the stories whose id contains one of the item's parts. An item the map
+ *   does not list has no stories, so no preview.
+ *
+ * @param itemName - The registry item name.
+ * @param mapping - The `stories` option of the site config.
+ * @param ladle - Every story in the playground.
+ * @returns The matching stories in playground order.
+ */
+export declare function storiesOf(itemName: string, mapping: SiteStories | undefined, ladle: LadleStoryMap): LadleStory[];
+/**
+ * The story the landing page's "Preview" button opens: `<item>--default` when it is one of the
+ * item's stories, else its first one.
+ *
+ * @param itemName - The registry item name.
+ * @param stories - The item's stories, from {@link storiesOf}.
+ * @returns A story id, or `undefined` for an item without stories.
+ */
+export declare function previewStoryOf(itemName: string, stories: readonly LadleStory[]): string | undefined;
+/**
+ * The story the live preview shows first: `defaultStory` as an item name (its preview story), or
+ * as a story id. `undefined` when it names neither, so the page falls back to its first story.
+ *
+ * @param defaultStory - The `defaultStory` option.
+ * @param previewStories - Item name → preview story id.
+ * @param ladle - Every story in the playground.
+ * @returns A story id, or `undefined`.
+ */
+export declare function defaultStoryOf(defaultStory: string | undefined, previewStories: Readonly<Record<string, string>>, ladle: LadleStoryMap): string | undefined;
+/** One generated HTML page. */
+interface SitePage {
+  /** Path inside `site/`, with forward slashes: `index.html`, `components/button/index.html`. */
+  path: string;
+  html: string;
+}
+/** Everything the pages are rendered from. */
+interface SiteRenderInput {
+  config: ResolvedSiteConfig;
+  index: RegistryIndex;
+  /** Full items with file contents, one per entry of `index.items`. */
+  items: readonly RegistryItem[];
+  /** Where the item JSON files are served. */
+  baseUrl: string;
+  version: string;
+  /** Every story of the Ladle playground; `{}` without a playground. */
+  ladle: LadleStoryMap;
+  /** The playground is part of the site. */
+  playground: boolean;
+  /** The fonts stylesheet is part of the site. */
+  fonts: boolean;
+}
+/**
+ * Renders every page of the site, without touching the file system.
+ *
+ * @param input - Config, the registry and what the site contains.
+ * @returns The landing page and one page per item.
+ */
+export declare function renderSiteFiles(input: SiteRenderInput): SitePage[];
+/**
+ * Checks that a built playground loads its assets from where the site serves it.
+ *
+ * A Ladle build made without `--base <site path>playground/` asks for `/assets/...`, which is a
+ * 404 under `site/playground/`, so every preview iframe stays blank.
+ *
+ * @param html - The text of `playground/dist/index.html`.
+ * @param base - The expected base, from {@link playgroundBase}.
+ * @throws {@link RegistrySiteError} with code `PLAYGROUND_BASE_MISMATCH` when an asset URL is
+ * absolute but outside `base`.
+ */
+export declare function checkPlaygroundBase(html: string, base: string): void;
+/** Options of {@link buildRegistrySite}. */
+interface BuildRegistrySiteOptions {
+  /** The repo root. Defaults to the current folder. */
+  root?: string | undefined;
+  /** The config object, or the path of the config file. Defaults to `registry/site.config.mjs`. */
+  config?: RegistrySiteConfig | string | undefined;
+  /** Environment variables (`REGISTRY_BASE_URL`, `SITE_BASE_PATH`, `GITHUB_REPOSITORY`). */
+  env?: SiteEnv | undefined;
+  /** Path the site is served from. Defaults to `SITE_BASE_PATH`, else `/`. */
+  siteBasePath?: string | undefined;
+  /** Build without the playground even when `playground/dist` exists. */
+  playground?: boolean | undefined;
+  /** Receives one line of progress. Defaults to writing to stdout. */
+  log?: ((line: string) => void) | undefined;
+}
+/** What {@link buildRegistrySite} did. */
+interface BuildRegistrySiteResult {
+  /** `false` when `integr8.site` is `false`: nothing was built. */
+  enabled: boolean;
+  siteDir: string;
+  /** Number of HTML pages written. */
+  pages: number;
+  fonts: boolean;
+  playground: boolean;
+  baseUrl: string;
+}
+/**
+ * Loads and validates a site config file.
+ *
+ * @param root - The repo root.
+ * @param file - The config file, relative to `root`. Defaults to `registry/site.config.mjs`.
+ * @returns The default export of the file.
+ * @throws {@link RegistrySiteError} with code `CONFIG_NOT_FOUND` when the file is missing.
+ */
+export declare function loadSiteConfig(root: string, file?: string): Promise<RegistrySiteConfig>;
+/**
+ * Builds the registry site into `site/`: the landing page, one page per item, the registry JSON
+ * (`r/`), the fonts and the Ladle playground. Needs `dist/registry/` (the registry builder's
+ * output) and, for live previews, `playground/dist/` built with the base from
+ * {@link playgroundBase}.
+ *
+ * Does nothing (and does not fail) when `"integr8": { "site": false }` is set in `package.json`.
+ *
+ * @param options - Root, config, environment and site path; all optional.
+ * @returns What was built.
+ * @throws {@link ConfigError} with code `INVALID_OPTION` for a bad config,
+ * {@link RegistrySiteError} for a missing config, registry or fonts, a bad switch value, or a
+ * playground built with the wrong `--base`.
+ */
+export declare function buildRegistrySite(options?: BuildRegistrySiteOptions): Promise<BuildRegistrySiteResult>;
+/** A module and the minified bytes it adds to a bundle. */
+interface ModuleSize {
+  /** The module path as esbuild reports it (forward slashes). */
+  path: string;
+  bytes: number;
+}
+/** The modules of one package in a bundle. */
+interface PackageSize {
+  /** Package name, or the own-code label for this package's built files. */
+  name: string;
+  /** Minified bytes of all its modules in the bundle. */
+  bytes: number;
+  /** Its modules, largest first. */
+  modules: ModuleSize[];
+}
+/** One export's measured size. */
+interface ExportSize {
+  name: string;
+  minifiedBytes: number;
+  brotliBytes: number;
+  /** The package with the most bytes in its bundle. */
+  largest?: string | undefined;
+}
+/** Label for this package's own built files, when none is given. */
+export declare const OWN_CODE = "this package (dist)";
+/**
+ * The package a bundled module belongs to: the name after the last `node_modules/` (with its
+ * scope), `ownCode` for `dist/`, and `(other)` for anything else (such as `<stdin>`).
+ *
+ * @param path - The module path.
+ * @param ownCode - Label for this package's own code.
+ * @returns A package name or label.
+ */
+export declare function packageOf(path: string, ownCode?: string): string;
+/**
+ * Groups the inputs of one esbuild output by package, largest first. Modules that add no bytes
+ * (removed by tree shaking) are left out.
+ *
+ * @param inputs - `metafile.outputs[file].inputs`.
+ * @param ownCode - Label for this package's own code.
+ * @returns One entry per package.
+ */
+export declare function groupByPackage(inputs: Readonly<Record<string, {
+  bytesInOutput: number;
+}>>, ownCode?: string): PackageSize[];
+/** `12345` → `12.35 kB` (1 kB = 1000 bytes, like size-limit). */
+export declare function formatKb(bytes: number): string;
+/** The part of a module path after its package folder (or after `dist/`), for short lines. */
+export declare function shortPath(path: string): string;
+/** Input of {@link formatReport}. */
+interface SizeReport {
+  /** For example `import { DatePicker }`. */
+  label: string;
+  /** From {@link groupByPackage}. */
+  groups: readonly PackageSize[];
+  /** Size of the minified bundle. */
+  minifiedBytes: number;
+  /** Size of the minified bundle after brotli. */
+  brotliBytes: number;
+  /** Largest modules listed under each package. Default 3. */
+  topModules?: number | undefined;
+}
+/**
+ * The text report for one import: totals, then one line per package with its minified size, an
+ * estimate of its brotli share, and its share of the bundle, then its largest modules.
+ *
+ * The brotli share of a package is estimated from its minified share: compression works on the
+ * whole bundle, so an exact per-package brotli size does not exist.
+ *
+ * @param report - The measured import.
+ * @returns Text, one line per row.
+ */
+export declare function formatReport(report: SizeReport): string;
+/**
+ * One line per export, largest brotli size first: the overview printed when no export is named.
+ *
+ * @param rows - The measured exports.
+ * @returns Text, one line per export.
+ */
+export declare function formatSummary(rows: readonly ExportSize[]): string;
+/**
+ * The runtime export names of a module, from esbuild's metafile (`outputs[file].exports`),
+ * sorted. Names starting with `_` are left out.
+ *
+ * @param exportNames - The names esbuild reports.
+ * @returns Unique public names.
+ */
+export declare function publicExports(exportNames: readonly string[]): string[];
+/**
+ * The file for a URL path: folders serve their `index.html`; `null` for paths outside the root
+ * or without a file.
+ *
+ * @param root - The folder to serve.
+ * @param urlPath - The path of the request URL.
+ * @returns An absolute file path, or `null`.
+ */
+export declare function resolveSiteFile(root: string, urlPath: string): Promise<string | null>;
+/**
+ * Creates (does not start) the static server for a folder.
+ *
+ * @param root - The folder to serve, normally `site/`.
+ * @returns A Node HTTP server. Folders without a trailing slash are redirected, so relative
+ * links on the page resolve; responses are never cached.
+ */
+export declare function createSiteServer(root: string): Server;
+/**
+ * Serves a folder on a port and resolves when it is listening.
+ *
+ * @param root - The folder to serve.
+ * @param port - The port (`0` picks a free one).
+ * @returns The running server.
+ */
+export declare function serveSite(root: string, port: number): Promise<Server>;
+/** What the command needs from the outside; tests replace these. */
+interface CliDeps {
+  /** The repo root. */
+  cwd: string;
+  env: SiteEnv;
+  /** Normal output. */
+  log: (line: string) => void;
+  /** Error output. */
+  error: (line: string) => void;
+  /** Runs a shell command in the repo and returns its exit code. */
+  run: (command: string, cwd: string, env: SiteEnv) => Promise<number>;
+  /** Starts the static server. */
+  serve: typeof serveSite;
+}
+/** The usage text. */
+export declare const USAGE = "Usage: integr8-registry-site <command> [options]\n\nCommands:\n  build     Build site/ (assets, Ladle playground, registry JSON, pages).\n  serve     Serve site/ on http://localhost:4173 (PORT=5000 to change).\n  dev       build, then serve. The playground is always built for http://localhost:<port>/.\n  enabled   Print true or false: the value of \"integr8.site\" in package.json.\n  size      Bundle-size breakdown of the package's exports (needs \"bundleSizes\" in the config).\n\nOptions:\n  --config <file>           Site config. Default: registry/site.config.mjs\n  --site-base-path <path>   Path the site is served from. Default: $SITE_BASE_PATH, else /\n  --no-playground           Build without the Ladle playground (no live previews)\n\nThe site is off when package.json has \"integr8\": { \"site\": false }: every command then\nprints a note and exits with code 0.";
+/**
+ * Runs the `integr8-registry-site` command.
+ *
+ * @param argv - The arguments after the program name.
+ * @param deps - Working folder, environment, output and process runner (default: the real ones).
+ * @returns The exit code: `0` on success and when the site is switched off, `1` on an error.
+ */
+export declare function runCli(argv: readonly string[], deps?: CliDeps): Promise<number>;
+/** A group of items on the landing page and in the sidebar. */
+interface SiteGroup<T> {
+  id: string;
+  label: string;
+  items: T[];
+}
+/** Escapes text for HTML content and attribute values. */
+export declare function escapeHtml(text: unknown): string;
+/** The short label of a registry type: `registry:ui` → `component`. */
+export declare function typeLabel(type: string): string;
+/**
+ * Groups registry items by their first category, in the order of `categories`. Items without a
+ * known category go last, under "Other". Without `categories`, the groups are the categories
+ * found in the items, in order of first appearance (labelled from their ids).
+ *
+ * @param items - Registry items.
+ * @param categories - Ordered `[id, label]` pairs, from the site config.
+ * @returns Only the groups that have items.
+ */
+export declare function groupItems<T extends {
+  name: string;
+  categories?: string[] | undefined;
+}>(items: readonly T[], categories?: readonly SiteEntry[] | undefined): SiteGroup<T>[];
+/** Options for the Markdown renderers. */
+interface MarkdownOptions {
+  /** Link target of inline code that names a documented export. */
+  linkFor?: ((name: string) => string | null | undefined) | undefined;
+}
+/**
+ * Inline Markdown: `code`, **bold** and [links](url). Inline code that names a documented
+ * export becomes a link to it, through `linkFor`.
+ *
+ * @param text - Markdown text on one line.
+ * @param options - `linkFor`, to link documented exports.
+ * @returns HTML.
+ */
+export declare function inlineMarkdown(text: string, options?: MarkdownOptions): string;
+/**
+ * Block Markdown for TSDoc text: paragraphs, `-` lists and fenced code blocks.
+ *
+ * @param markdown - Markdown text.
+ * @param options - `linkFor`, to link documented exports.
+ * @returns HTML.
+ */
+export declare function renderMarkdown(markdown: string | undefined, options?: MarkdownOptions): string;
+/** The brand parts of the page header. */
+interface ShellBrand {
+  /** Product name; the header link is labelled `<name> home`. */
+  name: string;
+  /** Shown after `integr8/`. */
+  slug: string;
+  /** Two letters in the badge. */
+  mark: string;
+}
+/** Options of {@link renderShell}. */
+interface ShellOptions {
+  /** Page title. */
+  title: string;
+  /** Meta description. */
+  description: string;
+  /** Header and footer texts. */
+  brand: ShellBrand;
+  /** Relative path from the page to the site root (`''` or `../../`). */
+  root?: string | undefined;
+  /** Fonts stylesheet, relative to the site root. */
+  fontsHref?: string | undefined;
+  /** Link to the source repository. */
+  repositoryUrl?: string | undefined;
+  /** Playground link in the header, relative to the site root. */
+  playgroundHref?: string | undefined;
+  /** Text at the start of the footer. */
+  footerNote: string;
+  /** The page's `<main>`. */
+  body: string;
+  /** Extra page script (plain JavaScript). */
+  script?: string | undefined;
+}
+/**
+ * The page shell shared by every page.
+ *
+ * @param options - Title, brand, links, body and script of the page.
+ * @returns The full HTML document.
+ */
+export declare function renderShell(options: ShellOptions): string;
+/**
+ * The slash-terminated path a site is served from: `''` and `/` → `/`, `ui` → `/ui/`.
+ *
+ * @param path - A path such as `/ui/` or the `SITE_BASE_PATH` variable.
+ * @returns A path that starts and ends with `/`.
+ */
+export declare function normalizeSitePath(path: string | undefined): string;
+/**
+ * The `--base` the Ladle playground must be built with so that its assets load from where the
+ * site serves it: `<site path>playground/`.
+ *
+ * @param sitePath - The path the site is served from (`/` locally, `/repo/` on GitHub Pages).
+ * @returns For example `/playground/` or `/integr8-ui/playground/`.
+ */
+export declare function playgroundBase(sitePath: string | undefined): string;
+/** A prop, parameter, field or enum member in an API table. */
+interface DocMember {
+  name: string;
+  type: string;
+  optional: boolean;
+  defaultValue?: string | undefined;
+  /** Markdown. */
+  description: string;
+  deprecated?: boolean;
+}
+/** What kind of export a {@link ExportDoc} describes. */
+type ExportKind = "component" | "hook" | "function" | "constant" | "class" | "interface" | "type" | "enum";
+/** The documentation of one exported declaration. */
+interface ExportDoc {
+  name: string;
+  kind: ExportKind;
+  /** Markdown. */
+  summary: string;
+  signature: string;
+  params?: DocMember[];
+  /** Return type. */
+  returns?: string;
+  /** Markdown from `@returns`. */
+  returnsDescription?: string;
+  members?: DocMember[];
+  extends?: string[];
+  /** Markdown (usually a fenced code block). */
+  examples: string[];
+  /** Markdown. */
+  throws: string[];
+  /** Markdown; set when the export is deprecated. */
+  deprecated?: string;
+  /** For components: the type of the props parameter. */
+  propsType?: string;
+  /** For components: defaults from the props destructuring. */
+  propDefaults?: Record<string, string>;
+}
+/**
+ * The documentation of every exported declaration in a file, in source order. Components get
+ * the defaults from their props destructuring copied onto their props type's members.
+ *
+ * @param fileName - Used for the parser (`.tsx` enables JSX).
+ * @param content - The file's text.
+ * @returns One entry per documented export.
+ */
+export declare function extractDocs(fileName: string, content: string): ExportDoc[];
+/** An export's docs with the file it comes from. */
+type ItemExportDoc = ExportDoc & {
+  file: string;
+};
+/**
+ * Every documented export of an item, the main one first (the export whose kebab-case name is
+ * the item name, for example `Button` for `button`), then in file and source order.
+ *
+ * @param item - A full registry item (with file contents).
+ * @returns The exports with their docs.
+ */
+export declare function itemDocs(item: Pick<RegistryItem, "name" | "files">): ItemExportDoc[];
+/**
+ * A shadcn item's `css` object as CSS text: selectors and at-rules become blocks, strings
+ * become declarations, empty objects become block-less at-rules (`@import "x";`).
+ *
+ * @param css - The item's `css` object.
+ * @param indent - Indentation of the first level.
+ * @returns CSS text.
+ */
+export declare function cssToText(css: Record<string, unknown>, indent?: string): string;
+/**
+ * Import lines for the value exports of each file:
+ * `import { Button } from '@/components/ui/button';`.
+ *
+ * @param docs - The exports of an item, from {@link itemDocs}.
+ * @returns One line per file.
+ */
+export declare function importLines(docs: readonly ItemExportDoc[]): string[];
+/** One item in the sidebar and the previous/next links. */
+interface ItemRef {
+  name: string;
+  title?: string | undefined;
+}
+/** The item the page documents. */
+interface ItemPageInput {
+  /** The full registry item (with file contents). */
+  item: RegistryItem;
+  /** Its Ladle stories. */
+  stories?: readonly LadleStory[] | undefined;
+  /** Names of the items that depend on it. */
+  usedBy?: readonly string[] | undefined;
+}
+/** The site-wide facts an item page needs. */
+interface ItemPageSite {
+  /** The resolved site config. */
+  config: ResolvedSiteConfig;
+  /** Where the item JSON files are served. */
+  baseUrl: string;
+  /** Package version. */
+  version: string;
+  /** Package name, for the footer. */
+  registryName: string;
+  /** Every item, grouped (sidebar). */
+  groups: readonly SiteGroup<ItemRef>[];
+  /** Every item in page order (previous/next). */
+  order: readonly ItemRef[];
+  /** Export name → item name, for links. */
+  exportOwners: ReadonlyMap<string, string>;
+  /** Folder of the item pages, relative to the site root. Defaults to `components/`. */
+  docsPath?: string | undefined;
+  /** Ladle playground, relative to the site root. */
+  playgroundPath?: string | undefined;
+  /** Fonts stylesheet, relative to the site root. */
+  fontsHref?: string | undefined;
+}
+/**
+ * Renders the documentation page of one registry item.
+ *
+ * @param page - The item, its stories and the items that use it.
+ * @param site - Config, URLs, the item list and the optional playground and fonts.
+ * @returns The full HTML document.
+ */
+export declare function renderItemPage(page: ItemPageInput, site: ItemPageSite): string;
+/** Options of {@link renderRegistryPage}. */
+interface LandingOptions {
+  /** The resolved site config (brand, categories, setup, themes, ui). */
+  config: ResolvedSiteConfig;
+  /** Where the item JSON files are served. */
+  baseUrl: string;
+  /** The package version the registry was built from. */
+  version: string;
+  /**
+   * Relative path of the Ladle build, for example `playground/`. Leave out when the playground
+   * is not part of the site.
+   */
+  playgroundPath?: string | undefined;
+  /** Relative path of the self-hosted fonts stylesheet. */
+  fontsHref?: string | undefined;
+  /**
+   * Relative folder of the item pages, for example `components/` (each item at
+   * `components/<name>/`). Leave out when there are none.
+   */
+  docsPath?: string | undefined;
+  /** Item name → the Ladle story id its "Preview" button opens. Items without one get no button. */
+  previewStories?: Readonly<Record<string, string>> | undefined;
+  /** Story id shown first in the live preview. */
+  defaultStory?: string | undefined;
+}
+/**
+ * Renders the landing page.
+ *
+ * @param index - The registry index (`registry.json`).
+ * @param options - Config, URLs and the optional playground, fonts and item pages.
+ * @returns The full HTML document.
+ */
+export declare function renderRegistryPage(index: RegistryIndex, options: LandingOptions): string;
+/**
+ * Codes carried by {@link RegistrySiteError}.
+ *
+ * - `CONFIG_NOT_FOUND`: the site config file does not exist.
+ * - `INVALID_SWITCH`: `integr8.site` in `package.json` is neither `true` nor `false`.
+ * - `REGISTRY_NOT_BUILT`: `dist/registry/registry.json` is missing, so there is nothing to render.
+ * - `PLAYGROUND_BASE_MISMATCH`: the Ladle playground was built with a different `--base` than the
+ *   site serves it from, so its preview iframes would be blank.
+ * - `UI_PACKAGE_NOT_FOUND`: `fonts: 'copy-from-ui'` needs the installed ui package and it is
+ *   not there.
+ * - `STEP_FAILED`: a build step (Ladle, the registry builder, the assets script) exited with an error.
+ * - `BUNDLE_SIZES_UNAVAILABLE`: the bundle-size breakdown is not configured, or its input is missing.
+ */
+type RegistrySiteErrorCode = "CONFIG_NOT_FOUND" | "INVALID_SWITCH" | "REGISTRY_NOT_BUILT" | "PLAYGROUND_BASE_MISMATCH" | "UI_PACKAGE_NOT_FOUND" | "STEP_FAILED" | "BUNDLE_SIZES_UNAVAILABLE";
+/**
+ * Thrown while building the registry site, for problems with the repo's files rather than with
+ * the options (those are a `ConfigError` with code `INVALID_OPTION`).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await buildRegistrySite();
+ * } catch (error) {
+ *   if (error instanceof RegistrySiteError && error.code === 'REGISTRY_NOT_BUILT') {
+ *     // run the registry build first
+ *   }
+ * }
+ * ```
+ */
+export declare class RegistrySiteError extends Error {
+  /** Always `'RegistrySiteError'`. */
+  override readonly name: "RegistrySiteError";
+  /** Machine-readable reason for the error. */
+  readonly code: RegistrySiteErrorCode;
+  /**
+   * @param code - Machine-readable reason for the error.
+   * @param message - Human-readable description.
+   * @param options - Standard error options, such as `cause`.
+   */
+  constructor(code: RegistrySiteErrorCode, message: string, options?: ErrorOptions);
+}
+/**
+ * Whether the registry site is on, from `integr8.site` in a parsed `package.json`.
+ *
+ * - key missing: on (a repo that calls the site workflow wants a site)
+ * - `"integr8": { "site": false }`: off
+ * - `"integr8": { "site": true }`: on
+ *
+ * This is the only on/off switch. The reusable workflow `registry-site.yml` reads the same key,
+ * and the `integr8-registry-site` commands exit with code 0 without building when it is `false`.
+ *
+ * @param pkg - The parsed `package.json`.
+ * @returns `false` only when `integr8.site` is `false`.
+ * @throws {@link RegistrySiteError} with code `INVALID_SWITCH` for any other value, so a typo
+ * such as `"site": "false"` never silently builds (or skips) the site.
+ *
+ * @example
+ * ```ts
+ * readSiteSwitch({ name: 'x', integr8: { site: false } }); // false
+ * readSiteSwitch({ name: 'x' }); // true
+ * ```
+ */
+export declare function readSiteSwitch(pkg: unknown): boolean;
+/**
+ * Reads `package.json` in a folder and returns the parsed file with its switch.
+ *
+ * @param root - The repo root.
+ * @returns The parsed `package.json` and `enabled`, the result of {@link readSiteSwitch}.
+ * @throws {@link RegistrySiteError} with code `INVALID_SWITCH` for a bad switch value.
+ */
+export declare function readPackageAndSwitch(root: string): Promise<{
+  pkg: Record<string, unknown>;
+  enabled: boolean;
+}>;
+export { type BuildRegistrySiteOptions, type BuildRegistrySiteResult, type CliDeps, ConfigError, type ConfigErrorCode, type DocMember, type ExportDoc, type ExportKind, type ExportSize, type ItemPageInput, type ItemPageSite, type ItemRef, type LadleStory, type LadleStoryMap, type LandingOptions, type MarkdownOptions, type ModuleSize, type PackageSize, type RegistryFile, type RegistryIndex, type RegistryIndexItem, type RegistryItem, type RegistrySiteConfig, type RegistrySiteErrorCode, type ResolvedSiteConfig, type ShellOptions, type SiteBrand, type SiteBundleSizes, type SiteCommands, type SiteCopy, type SiteEntry, type SiteEnv, type SiteFonts, type SiteGroup, type SitePackage, type SitePage, type SiteRenderInput, type SiteSetup, type SiteSetupExtra, type SiteSetupStep, type SiteStories, type SiteUi, type SizeReport };