@tdacorp/hyle-sdk 0.1.1 → 0.2.1

package/dist/next.cjs

@@ -21,13 +21,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var next_exports = {};
 __export(next_exports, {
   createRevalidateRoute: () => createRevalidateRoute,
+  fetchResolver: () => fetchResolver,
   hyleMetadata: () => hyleMetadata,
-  hylePage: () => hylePage
+  hylePage: () => hylePage,
+  hyleSitemap: () => hyleSitemap,
+  workspaceTags: () => workspaceTags
 });
 module.exports = __toCommonJS(next_exports);
 
 // src/next/page.tsx
-var import_navigation = require("next/navigation");
+var import_navigation2 = require("next/navigation");
 
 // src/errors.ts
 var Cp1ClientError = class extends Error {
@@ -268,6 +271,46 @@ function okResponse(purged) {
   });
 }
 
+// src/sitemap.ts
+var PAGE_LIMIT = 100;
+var DEFAULT_MAX_PAGES = 20;
+var SECTION_SLUG = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+var UNSAFE_PATH = /[\\?#<>&"'\u0000- \u007f]/;
+async function listPublicationPaths(options) {
+  const maxPages = options.maxPages ?? DEFAULT_MAX_PAGES;
+  const prefix = `${options.basePath}/`;
+  const indexes = [options.basePath || "/"];
+  for (const slug of options.sections ?? []) if (slug !== "posts" && SECTION_SLUG.test(slug)) indexes.push(`${options.basePath}/${slug}`);
+  const found = /* @__PURE__ */ new Map();
+  let complete = true;
+  try {
+    for (const index of new Set(indexes)) {
+      let cursor;
+      for (let page = 0; page < maxPages; page++) {
+        const result = await options.client.resolve({
+          path: index,
+          limit: PAGE_LIMIT,
+          ...options.locale !== void 0 ? { locale: options.locale } : {},
+          ...cursor !== void 0 ? { cursor } : {}
+        });
+        if (result.kind !== "list") {
+          complete = false;
+          break;
+        }
+        for (const item of result.items) {
+          if (item.canonical_path.startsWith(prefix) && !UNSAFE_PATH.test(item.canonical_path)) found.set(item.canonical_path, item.published_at);
+        }
+        if (!result.next_cursor) break;
+        if (page === maxPages - 1) complete = false;
+        cursor = result.next_cursor;
+      }
+    }
+  } catch {
+    complete = false;
+  }
+  return { paths: [...found].map(([path, publishedAt]) => ({ path, publishedAt })), complete };
+}
+
 // src/react/content.tsx
 var import_hast_util_to_jsx_runtime = require("hast-util-to-jsx-runtime");
 var import_react = require("react");
@@ -513,7 +556,10 @@ var en = {
   rdBody: "You are being taken to its new address.",
   from: "From",
   to: "To",
-  rdFallback: "If nothing happens, go to the new address."
+  rdFallback: "If nothing happens, go to the new address.",
+  unKind: "Unavailable",
+  unTitle: "This page is temporarily unavailable",
+  unBody: "The content could not be loaded. Please try again in a moment."
 };
 var fr = {
   toc: "Sur cette page",
@@ -549,7 +595,10 @@ var fr = {
   rdBody: "Vous \xEAtes redirig\xE9 vers sa nouvelle adresse.",
   from: "De",
   to: "Vers",
-  rdFallback: "Si rien ne se passe, allez \xE0 la nouvelle adresse."
+  rdFallback: "Si rien ne se passe, allez \xE0 la nouvelle adresse.",
+  unKind: "Indisponible",
+  unTitle: "Cette page est momentan\xE9ment indisponible",
+  unBody: "Le contenu n'a pas pu \xEAtre charg\xE9. R\xE9essayez dans un instant."
 };
 var es = {
   toc: "En esta p\xE1gina",
@@ -585,7 +634,10 @@ var es = {
   rdBody: "Te estamos llevando a su nueva direcci\xF3n.",
   from: "Desde",
   to: "A",
-  rdFallback: "Si no pasa nada, ve a la nueva direcci\xF3n."
+  rdFallback: "Si no pasa nada, ve a la nueva direcci\xF3n.",
+  unKind: "No disponible",
+  unTitle: "Esta p\xE1gina no est\xE1 disponible por el momento",
+  unBody: "No se pudo cargar el contenido. Int\xE9ntalo de nuevo en un momento."
 };
 var TABLE = { en, fr, es };
 function stringsFor(locale) {
@@ -932,6 +984,9 @@ function DocsPage({ article, ...base }) {
   ] }) });
 }
 
+// src/next/options.ts
+var import_navigation = require("next/navigation");
+
 // src/next/paths.ts
 function normalizeBasePath(basePath) {
   const value = (basePath ?? "").replace(/\/+$/, "");
@@ -939,6 +994,7 @@ function normalizeBasePath(basePath) {
   if (!/^\/[^\s?#\\]+$/.test(value) || value.includes("//")) throw new TypeError(`basePath must look like "/learn", got "${basePath}"`);
   return value;
 }
+var MAX_PATH_LENGTH = 1024;
 function sitePathFrom(basePath, segments) {
   const decoded = [];
   for (const raw of segments ?? []) {
@@ -948,10 +1004,12 @@ function sitePathFrom(basePath, segments) {
     } catch {
       return void 0;
     }
+    if (segment !== segment.normalize("NFC")) return void 0;
     if (segment === "" || segment === "." || segment === ".." || /[/\\\u0000-\u001f\u007f]/.test(segment)) return void 0;
     decoded.push(segment);
   }
-  return decoded.length === 0 ? basePath || "/" : `${basePath}/${decoded.join("/")}`;
+  const path = decoded.length === 0 ? basePath || "/" : `${basePath}/${decoded.join("/")}`;
+  return path.length > MAX_PATH_LENGTH ? void 0 : path;
 }
 function safeRedirectTarget(to) {
   if (typeof to !== "string" || !to.startsWith("/") || to.startsWith("//")) return void 0;
@@ -961,19 +1019,24 @@ function safeRedirectTarget(to) {
 // src/next/resolve.ts
 var DEFAULT_REVALIDATE = 300;
 var MAX_TAGS2 = 64;
-function fetchTags(workspaceId, sections = []) {
+function workspaceTags(workspaceId, sections = []) {
+  const workspaceTag = `hyle:1:ws:${workspaceId}`;
+  if (!isValidCacheTag(workspaceTag)) throw new TypeError("hyle: `workspaceId` is not a valid workspace id (a uuid)");
   const slugs = /* @__PURE__ */ new Set(["posts", ...sections]);
-  return [`hyle:1:ws:${workspaceId}`, ...[...slugs].map((s) => `hyle:1:sec:${workspaceId}:${s}`)].filter(isValidCacheTag).slice(0, MAX_TAGS2);
+  const tags = [...slugs].map((slug) => `hyle:1:sec:${workspaceId}:${slug}`);
+  if (!tags.every(isValidCacheTag)) throw new TypeError("hyle: a configured `sections` slug cannot be used in a cache tag (printable ASCII, at most 200 characters)");
+  return [workspaceTag, ...tags].slice(0, MAX_TAGS2);
 }
 function fetchResolver(options) {
   if (!options.workspaceId) throw new TypeError("hylePage: `workspaceId` is required for the fetch cache (or pass a cachedResolver)");
   const client = createHyleClient({ baseUrl: options.baseUrl, token: options.token });
   const revalidate = options.revalidate ?? DEFAULT_REVALIDATE;
-  const tags = fetchTags(options.workspaceId, options.sections);
-  return (path, locale, limit) => client.resolve({
+  const tags = workspaceTags(options.workspaceId, options.sections);
+  return (path, locale, limit, cursor) => client.resolve({
     path,
     ...locale !== void 0 ? { locale } : {},
     ...limit !== void 0 ? { limit } : {},
+    ...cursor !== void 0 ? { cursor } : {},
     init: { next: { revalidate, tags } }
   });
 }
@@ -982,77 +1045,135 @@ function fetchResolver(options) {
 function resolverFor(options) {
   return options.resolver ?? fetchResolver(options);
 }
-var LOCALE_TAG = /^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$/;
+var CURSOR = /^[A-Za-z0-9_-]{1,256}$/;
+var validCursor = (value) => typeof value === "string" && CURSOR.test(value) ? value : void 0;
+var LOCALE_TAG = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+var MAX_LOCALE_LENGTH = 35;
 function routeContext(options, params) {
   const basePath = normalizeBasePath(options.basePath);
   const segments = params[options.param ?? "hyle"];
   const path = sitePathFrom(basePath, typeof segments === "string" ? [segments] : segments);
   const given = typeof options.locale === "function" ? options.locale(params) : options.locale;
-  const locale = typeof given === "string" && LOCALE_TAG.test(given) ? given : void 0;
+  const locale = typeof given === "string" && given.length <= MAX_LOCALE_LENGTH && LOCALE_TAG.test(given) ? given : void 0;
   const prefix = options.localePrefix ?? (() => "");
   const toHref = (sitePath, linkLocale = locale) => (linkLocale ? prefix(linkLocale) : "") + sitePath;
   return { basePath, path, locale, toHref };
 }
+function isRejectedRequest(error) {
+  (0, import_navigation.unstable_rethrow)(error);
+  return error instanceof Cp1ClientError && error.status >= 400 && error.status < 500 && ![401, 403, 429].includes(error.status);
+}
 
 // src/next/page.tsx
 var import_jsx_runtime5 = require("react/jsx-runtime");
 function hylePage(options) {
   const resolve = resolverFor(options);
-  return async function HylePage({ params }) {
+  return async function HylePage({ params, searchParams }) {
     const { path, locale, toHref } = routeContext(options, await params ?? {});
-    if (path === void 0) (0, import_navigation.notFound)();
-    const result = await resolve(path, locale, options.listLimit);
-    switch (result.kind) {
-      case "article": {
-        const props = { article: result, components: options.components, slots: options.slots, locale, toHref };
-        return options.layout === "docs" ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(DocsPage, { ...props }) : /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(ArticlePage, { ...props });
-      }
-      case "list":
-        return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(ListPage, { list: result, components: options.components, slots: options.slots, locale, toHref });
-      case "redirect": {
-        const to = safeRedirectTarget(result.to);
-        if (to === void 0) throw new Cp1ClientError("INVALID_RESPONSE", "hyle returned an unsafe redirect target", 502, "");
-        const target = safeRedirectTarget(toHref(to));
-        if (target === void 0) throw new Cp1ClientError("INVALID_RESPONSE", "hyle returned an unsafe redirect target", 502, "");
-        if (target === toHref(path)) (0, import_navigation.notFound)();
-        return result.status === 301 ? (0, import_navigation.permanentRedirect)(target) : (0, import_navigation.redirect)(target);
+    if (path === void 0) (0, import_navigation2.notFound)();
+    try {
+      const cursor = options.paginate === "searchParams" ? validCursor((await searchParams)?.cursor) : void 0;
+      const result = await resolve(path, locale, options.listLimit, cursor);
+      switch (result.kind) {
+        case "article": {
+          const props = { article: result, components: options.components, slots: options.slots, locale, toHref };
+          return options.layout === "docs" ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(DocsPage, { ...props }) : /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(ArticlePage, { ...props });
+        }
+        case "list": {
+          const list = options.list?.title ? { ...result, section: { ...result.section, title: options.list.title } } : result;
+          const next = options.paginate === "searchParams" ? validCursor(result.next_cursor) : void 0;
+          const olderHref = next ? `${toHref(path)}?cursor=${next}` : void 0;
+          return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(ListPage, { list, ...olderHref ? { olderHref } : {}, ...options.list?.description ? { description: options.list.description } : {}, components: options.components, slots: options.slots, locale, toHref });
+        }
+        case "redirect": {
+          const to = safeRedirectTarget(result.to);
+          if (to === void 0) throw new Cp1ClientError("INVALID_RESPONSE", "hyle returned an unsafe redirect target", 502, "");
+          const target = safeRedirectTarget(toHref(to));
+          if (target === void 0) throw new Cp1ClientError("INVALID_RESPONSE", "hyle returned an unsafe redirect target", 502, "");
+          if (target === toHref(path)) (0, import_navigation2.notFound)();
+          return result.status === 301 ? (0, import_navigation2.permanentRedirect)(target) : (0, import_navigation2.redirect)(target);
+        }
+        case "notfound":
+        case "disabled":
+          (0, import_navigation2.notFound)();
       }
-      case "notfound":
-      case "disabled":
-        (0, import_navigation.notFound)();
+    } catch (error) {
+      if (isRejectedRequest(error)) (0, import_navigation2.notFound)();
+      if (!options.onError) throw error;
+      console.error(`hyle: ${error instanceof Error ? error.name : "UnknownError"}`);
+      return options.onError(error);
     }
   };
 }
 
+// src/next/sitemap.ts
+var ISO_DATE = /^\d{4}-\d{2}-\d{2}T/;
+function httpsOrigin(origin) {
+  let url;
+  try {
+    url = new URL(origin);
+  } catch {
+    throw new TypeError("hyleSitemap: `origin` must be an https origin such as https://example.com");
+  }
+  if (url.protocol !== "https:" || url.origin !== origin.replace(/\/$/, "")) {
+    throw new TypeError("hyleSitemap: `origin` must be an https origin with no path, query or credentials");
+  }
+  return url.origin;
+}
+async function hyleSitemap(options) {
+  const origin = httpsOrigin(options.origin);
+  const resolve = resolverFor(options);
+  const locale = typeof options.locale === "string" ? options.locale : void 0;
+  const { basePath, toHref } = routeContext({ ...options, locale: () => locale }, {});
+  const client = { resolve: ({ path, locale: l, limit, cursor }) => resolve(path, l, limit, cursor) };
+  const { paths, complete } = await listPublicationPaths({ client, basePath, ...options.sections ? { sections: options.sections } : {}, ...locale ? { locale } : {} });
+  if (!complete && (options.onIncomplete === "throw" || options.onIncomplete === void 0 && paths.length === 0)) {
+    throw new Error("hyleSitemap: hyle could not be listed completely (see onIncomplete)");
+  }
+  return paths.map(({ path, publishedAt }) => ({
+    url: origin + encodeURI(toHref(path)),
+    ...ISO_DATE.test(publishedAt) && !Number.isNaN(Date.parse(publishedAt)) ? { lastModified: publishedAt } : {}
+  }));
+}
+
 // src/next/metadata.ts
 function hyleMetadata(options) {
   const resolve = resolverFor(options);
   return async function generateMetadata({ params }) {
     const { path, locale, toHref } = routeContext(options, await params ?? {});
     if (path === void 0) return {};
-    const result = await resolve(path, locale, options.listLimit);
-    if (result.kind === "list") return { title: result.section.title };
-    if (result.kind !== "article") return {};
-    const { publication: pub, alternates } = result;
-    const canonical = toHref(pub.canonical_path, pub.locale);
-    const description = pub.description ?? void 0;
-    return {
-      title: pub.title,
-      ...description ? { description } : {},
-      alternates: {
-        canonical,
-        ...alternates.length > 1 ? { languages: Object.fromEntries(alternates.map((a) => [a.locale, toHref(a.canonical_path, a.locale)])) } : {}
-      },
-      openGraph: {
-        type: "article",
+    try {
+      const result = await resolve(path, locale, options.listLimit);
+      if (result.kind === "list") {
+        const title = options.list?.title || result.section.title;
+        const description2 = options.list?.description;
+        return { title, ...description2 ? { description: description2 } : {}, openGraph: { title, ...description2 ? { description: description2 } : {} } };
+      }
+      if (result.kind !== "article") return {};
+      const { publication: pub, alternates } = result;
+      const canonical = toHref(pub.canonical_path, pub.locale);
+      const description = pub.description ?? void 0;
+      return {
         title: pub.title,
         ...description ? { description } : {},
-        url: canonical,
-        locale: pub.locale,
-        publishedTime: pub.published_at,
-        modifiedTime: pub.updated_at
-      }
-    };
+        alternates: {
+          canonical,
+          ...alternates.length > 1 ? { languages: Object.fromEntries(alternates.map((a) => [a.locale, toHref(a.canonical_path, a.locale)])) } : {}
+        },
+        openGraph: {
+          type: "article",
+          title: pub.title,
+          ...description ? { description } : {},
+          url: canonical,
+          locale: pub.locale,
+          publishedTime: pub.published_at,
+          modifiedTime: pub.updated_at
+        }
+      };
+    } catch (error) {
+      if (isRejectedRequest(error)) return {};
+      throw error;
+    }
   };
 }
 
@@ -1079,6 +1200,9 @@ function createRevalidateRoute(options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createRevalidateRoute,
+  fetchResolver,
   hyleMetadata,
-  hylePage
+  hylePage,
+  hyleSitemap,
+  workspaceTags
 });

package/dist/next.d.cts

@@ -1,7 +1,8 @@
 import { ReactElement } from 'react';
 import { H as HyleComponents, a as HyleSlots } from './types-DLWvqanV.cjs';
-import { F as FetchResolverOptions, H as HyleResolver } from './resolve-DrmTGaCr.cjs';
-import { Metadata } from 'next';
+import { F as FetchResolverOptions, H as HyleResolver } from './resolve-B_p0p4Zn.cjs';
+export { f as fetchResolver, w as workspaceTags } from './resolve-B_p0p4Zn.cjs';
+import { MetadataRoute, Metadata } from 'next';
 import { a as RevalidationCallbackRoute } from './revalidation-callback-D7Ms_Puz.cjs';
 import './types-DjXf6iPo.cjs';
 
@@ -28,6 +29,33 @@ interface CommonOptions {
     readonly layout?: "article" | "docs";
     /** Items per list page (server default 20, maximum 100). */
     readonly listLimit?: number;
+    /**
+     * Heading and description of the list page (the mount path's index). hyle names the default section after its slug
+     * ("Posts"); `list.title` replaces that in the page's h1, the `<title>` and Open Graph, and `list.description` fills the
+     * page description, `<meta name="description">` and Open Graph. Each falls back separately: title to the hyle section
+     * title, description to none. Article pages are unaffected.
+     */
+    readonly list?: {
+        readonly title?: string;
+        readonly description?: string;
+    };
+    /**
+     * `"searchParams"` makes list pages paginate: `?cursor=` is read, sent to hyle, and an "Older posts" link is built from
+     * `next_cursor`. Default off, and the trade-off is real: reading `searchParams` makes the route dynamic, so it can no longer
+     * be statically generated or served from ISR (hyle's fetch cache still applies). Leave it off when one page of `listLimit`
+     * items is enough. A malformed `cursor` is ignored (the first page is shown); one that is well-formed but unknown to hyle is a 404.
+     */
+    readonly paginate?: "searchParams";
+    /**
+     * Opt-in custom UI for transient or operational hyle failures (network error, timeout, 5xx, 401, 403, 429, a malformed
+     * response, a refused redirect target). Without it `hylePage` rethrows them, so Next keeps serving the last good ISR page
+     * when a revalidation fails (and a failure on a first render is an uncached 500). With it, the returned element is a NORMAL
+     * render: it is cached for the revalidate window and replaces the last good page for that long, so prefer a boundary
+     * (`error.tsx`) unless you want that. The `error` can carry `Cp1ClientError.message` and `requestId`: never render it.
+     * Only its name is logged. A 4xx rejection of the request (400, 404, ...) is always `notFound()` and never reaches this, and
+     * `notFound()` and redirects are Next control flow that always propagate.
+     */
+    readonly onError?: (error: unknown) => ReactElement;
 }
 /**
  * Pass either the fetch-cache settings (works with no host configuration) or a `resolver` from
@@ -40,6 +68,8 @@ type HyleNextOptions = CommonOptions & (({
 });
 interface PageProps {
     readonly params?: Promise<RouteParams>;
+    /** Read only with `paginate: "searchParams"`. */
+    readonly searchParams?: Promise<Record<string, string | string[] | undefined>>;
 }
 
 /**
@@ -50,17 +80,45 @@ interface PageProps {
  * in front, and 301 maps to permanentRedirect (308) while 307 maps to redirect (temporary). A target equal to the current
  * URL would loop, so it is treated as not found.
  *
+ * Failure: a 4xx rejection of the request (400, 404, ...) is `notFound()`. Every other failure (network error, timeout, 5xx,
+ * 401, 403, 429, a malformed response, a refused redirect target) is RETHROWN, so under ISR Next keeps serving the last good
+ * page when a revalidation fails, and a first-render failure is an uncached 500 rather than a cached soft 200. `onError`
+ * opts in to a custom element instead (see its docs). `notFound()` and redirects always propagate (`unstable_rethrow`).
+ *
  * Host requirement: no parent layout or page above the mount may export `dynamicParams = false`. Next inherits it, the
  * route is compiled with `"fallback": false` and every article not known at build time is a hard 404 (it falls through
  * to a `[locale]/[...rest]` catch-all). A page-level `dynamicParams = true` does not override a parent's false.
  */
 declare function hylePage(options: HyleNextOptions): (props: PageProps) => Promise<ReactElement>;
 
+type HyleSitemapOptions = HyleNextOptions & {
+    /** The site's public origin, for example "https://tdacorp.in": https, no path, query or credentials. */
+    readonly origin: string;
+    /** Section slugs to include besides the default section (their index must be `basePath/<slug>`). */
+    readonly sections?: readonly string[];
+    /**
+     * What to do when hyle fails or a listing is cut off. `"partial"`: return what was collected. `"throw"`: throw, so a build
+     * during a hyle outage fails instead of shipping a partial sitemap. Default: throw only when nothing was collected.
+     */
+    readonly onIncomplete?: "partial" | "throw";
+};
+/**
+ * Sitemap entries for the mount, to spread into the host's `app/sitemap.ts`: `[...staticEntries, ...(await hyleSitemap({ ...sameOptionsAsHylePage, origin }))]`.
+ * Uses the same resolver (so the same cache and tags) as `hylePage`, and `localePrefix` for the URLs. `locale` is used only
+ * when it is a string: a function of the route params is never called here, so the sitemap is for the default locale.
+ * It pages each section index through `listPublicationPaths`, so only the default section and the listed `sections` appear,
+ * at most 2000 pages per section; paths are percent-encoded and `lastModified` is the publish time (omitted if it is not an
+ * ISO date). An invalid `origin` throws; see `onIncomplete` for hyle failures.
+ */
+declare function hyleSitemap(options: HyleSitemapOptions): Promise<MetadataRoute.Sitemap>;
+
 /**
  * `export const generateMetadata = hyleMetadata({ ... })` with the same options as `hylePage`. Title, description, a canonical
  * URL in the page's own locale (so a fallback copy under another locale prefix points at the original), hreflang alternates
  * from the response's `alternates`, and Open Graph. Paths are relative: set `metadataBase` in the host's root layout.
- * Redirects, 404s and a switched-off read surface produce no metadata; `hylePage` handles those.
+ * Redirects, 404s and a switched-off read surface produce no metadata; `hylePage` handles those. A 4xx rejection of the request
+ * gives no metadata; any other failure (network, timeout, 5xx, 401, 403, 429) is rethrown, so a transient outage is not
+ * cached as a page; Next control flow is rethrown.
  */
 declare function hyleMetadata(options: HyleNextOptions): (props: PageProps) => Promise<Metadata>;
 
@@ -81,4 +139,4 @@ interface RevalidateRouteOptions {
  */
 declare function createRevalidateRoute(options: RevalidateRouteOptions): RevalidationCallbackRoute;
 
-export { FetchResolverOptions, type HyleNextOptions, HyleResolver, type PageProps, type RevalidateRouteOptions, type RouteParams, createRevalidateRoute, hyleMetadata, hylePage };
+export { FetchResolverOptions, type HyleNextOptions, HyleResolver, type HyleSitemapOptions, type PageProps, type RevalidateRouteOptions, type RouteParams, createRevalidateRoute, hyleMetadata, hylePage, hyleSitemap };

package/dist/next.d.ts

@@ -1,7 +1,8 @@
 import { ReactElement } from 'react';
 import { H as HyleComponents, a as HyleSlots } from './types-BNaGecO7.js';
-import { F as FetchResolverOptions, H as HyleResolver } from './resolve-Cz-3Q7T-.js';
-import { Metadata } from 'next';
+import { F as FetchResolverOptions, H as HyleResolver } from './resolve-fMx2W8RR.js';
+export { f as fetchResolver, w as workspaceTags } from './resolve-fMx2W8RR.js';
+import { MetadataRoute, Metadata } from 'next';
 import { a as RevalidationCallbackRoute } from './revalidation-callback-D7Ms_Puz.js';
 import './types-DjXf6iPo.js';
 
@@ -28,6 +29,33 @@ interface CommonOptions {
     readonly layout?: "article" | "docs";
     /** Items per list page (server default 20, maximum 100). */
     readonly listLimit?: number;
+    /**
+     * Heading and description of the list page (the mount path's index). hyle names the default section after its slug
+     * ("Posts"); `list.title` replaces that in the page's h1, the `<title>` and Open Graph, and `list.description` fills the
+     * page description, `<meta name="description">` and Open Graph. Each falls back separately: title to the hyle section
+     * title, description to none. Article pages are unaffected.
+     */
+    readonly list?: {
+        readonly title?: string;
+        readonly description?: string;
+    };
+    /**
+     * `"searchParams"` makes list pages paginate: `?cursor=` is read, sent to hyle, and an "Older posts" link is built from
+     * `next_cursor`. Default off, and the trade-off is real: reading `searchParams` makes the route dynamic, so it can no longer
+     * be statically generated or served from ISR (hyle's fetch cache still applies). Leave it off when one page of `listLimit`
+     * items is enough. A malformed `cursor` is ignored (the first page is shown); one that is well-formed but unknown to hyle is a 404.
+     */
+    readonly paginate?: "searchParams";
+    /**
+     * Opt-in custom UI for transient or operational hyle failures (network error, timeout, 5xx, 401, 403, 429, a malformed
+     * response, a refused redirect target). Without it `hylePage` rethrows them, so Next keeps serving the last good ISR page
+     * when a revalidation fails (and a failure on a first render is an uncached 500). With it, the returned element is a NORMAL
+     * render: it is cached for the revalidate window and replaces the last good page for that long, so prefer a boundary
+     * (`error.tsx`) unless you want that. The `error` can carry `Cp1ClientError.message` and `requestId`: never render it.
+     * Only its name is logged. A 4xx rejection of the request (400, 404, ...) is always `notFound()` and never reaches this, and
+     * `notFound()` and redirects are Next control flow that always propagate.
+     */
+    readonly onError?: (error: unknown) => ReactElement;
 }
 /**
  * Pass either the fetch-cache settings (works with no host configuration) or a `resolver` from
@@ -40,6 +68,8 @@ type HyleNextOptions = CommonOptions & (({
 });
 interface PageProps {
     readonly params?: Promise<RouteParams>;
+    /** Read only with `paginate: "searchParams"`. */
+    readonly searchParams?: Promise<Record<string, string | string[] | undefined>>;
 }
 
 /**
@@ -50,17 +80,45 @@ interface PageProps {
  * in front, and 301 maps to permanentRedirect (308) while 307 maps to redirect (temporary). A target equal to the current
  * URL would loop, so it is treated as not found.
  *
+ * Failure: a 4xx rejection of the request (400, 404, ...) is `notFound()`. Every other failure (network error, timeout, 5xx,
+ * 401, 403, 429, a malformed response, a refused redirect target) is RETHROWN, so under ISR Next keeps serving the last good
+ * page when a revalidation fails, and a first-render failure is an uncached 500 rather than a cached soft 200. `onError`
+ * opts in to a custom element instead (see its docs). `notFound()` and redirects always propagate (`unstable_rethrow`).
+ *
  * Host requirement: no parent layout or page above the mount may export `dynamicParams = false`. Next inherits it, the
  * route is compiled with `"fallback": false` and every article not known at build time is a hard 404 (it falls through
  * to a `[locale]/[...rest]` catch-all). A page-level `dynamicParams = true` does not override a parent's false.
  */
 declare function hylePage(options: HyleNextOptions): (props: PageProps) => Promise<ReactElement>;
 
+type HyleSitemapOptions = HyleNextOptions & {
+    /** The site's public origin, for example "https://tdacorp.in": https, no path, query or credentials. */
+    readonly origin: string;
+    /** Section slugs to include besides the default section (their index must be `basePath/<slug>`). */
+    readonly sections?: readonly string[];
+    /**
+     * What to do when hyle fails or a listing is cut off. `"partial"`: return what was collected. `"throw"`: throw, so a build
+     * during a hyle outage fails instead of shipping a partial sitemap. Default: throw only when nothing was collected.
+     */
+    readonly onIncomplete?: "partial" | "throw";
+};
+/**
+ * Sitemap entries for the mount, to spread into the host's `app/sitemap.ts`: `[...staticEntries, ...(await hyleSitemap({ ...sameOptionsAsHylePage, origin }))]`.
+ * Uses the same resolver (so the same cache and tags) as `hylePage`, and `localePrefix` for the URLs. `locale` is used only
+ * when it is a string: a function of the route params is never called here, so the sitemap is for the default locale.
+ * It pages each section index through `listPublicationPaths`, so only the default section and the listed `sections` appear,
+ * at most 2000 pages per section; paths are percent-encoded and `lastModified` is the publish time (omitted if it is not an
+ * ISO date). An invalid `origin` throws; see `onIncomplete` for hyle failures.
+ */
+declare function hyleSitemap(options: HyleSitemapOptions): Promise<MetadataRoute.Sitemap>;
+
 /**
  * `export const generateMetadata = hyleMetadata({ ... })` with the same options as `hylePage`. Title, description, a canonical
  * URL in the page's own locale (so a fallback copy under another locale prefix points at the original), hreflang alternates
  * from the response's `alternates`, and Open Graph. Paths are relative: set `metadataBase` in the host's root layout.
- * Redirects, 404s and a switched-off read surface produce no metadata; `hylePage` handles those.
+ * Redirects, 404s and a switched-off read surface produce no metadata; `hylePage` handles those. A 4xx rejection of the request
+ * gives no metadata; any other failure (network, timeout, 5xx, 401, 403, 429) is rethrown, so a transient outage is not
+ * cached as a page; Next control flow is rethrown.
  */
 declare function hyleMetadata(options: HyleNextOptions): (props: PageProps) => Promise<Metadata>;
 
@@ -81,4 +139,4 @@ interface RevalidateRouteOptions {
  */
 declare function createRevalidateRoute(options: RevalidateRouteOptions): RevalidationCallbackRoute;
 
-export { FetchResolverOptions, type HyleNextOptions, HyleResolver, type PageProps, type RevalidateRouteOptions, type RouteParams, createRevalidateRoute, hyleMetadata, hylePage };
+export { FetchResolverOptions, type HyleNextOptions, HyleResolver, type HyleSitemapOptions, type PageProps, type RevalidateRouteOptions, type RouteParams, createRevalidateRoute, hyleMetadata, hylePage, hyleSitemap };