@tenphi/cookbook 0.28.0 → 0.30.0

package/docs/plugins.md

@@ -22,13 +22,15 @@ export default defineConfig({
 });
 ```
 
+Install `@astrojs/markdown-remark` first; it is an optional Astro dependency
+that generated projects do not include. Astro's default Sätteri processor does
+not run remark or rehype plugins. Cookbook adds its transforms to whichever
+processor is configured, and `.mdx` pages use the same processor.
+
 ## GitHub alerts
 
 Cookbook renders GitHub alert blockquotes in Markdown and MDX without an extra
-plugin. `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION` map to the semantic
-note, tip, caution, and danger surfaces. For example:
-
-The default Astro integration is sufficient for alert rendering:
+plugin; the default Astro integration is enough:
 
 ```js cookbook-verify=github-alerts
 import cookbook from "@tenphi/cookbook";
@@ -43,22 +45,29 @@ Write the alert in a Markdown or MDX page:
 > Keep source documentation next to the code it describes.
 ```
 
+`NOTE` renders as a note, `TIP` and `IMPORTANT` as a tip, `WARNING` as a
+caution, and `CAUTION` as danger. Titles are English. Alerts use the same
+status palette roles as `Callout`: `info` for notes, `success` for tips,
+`warning` for cautions, and `danger` for danger.
+
 Customize the result through `theme.styles.MarkdownAlert`. Its named
-sub-elements are `Note`, `Tip`, `Caution`, `Danger`, `Title`, and
-`FirstContent`.
+sub-elements are `Title` and `FirstContent`. Style each kind with root states
+such as `[data-note]`, `[data-tip]`, `[data-caution]`, and `[data-danger]` in
+property state maps.
 
 ## Custom frontmatter
 
-Unknown frontmatter fields can be preserved as JSON metadata. Set
-`content.frontmatter: "preserve"`, then validate or add custom fields with
-`frontmatterSchema`:
+Cookbook keeps unknown frontmatter fields as JSON metadata by default
+(`content.frontmatter: "preserve"`); `"reject"` turns them into errors.
+Validate or add custom fields with `frontmatterSchema`:
 
 ```ts
 export default defineConfig({
   integrations: [
     cookbook({
       frontmatterSchema: {
-        parse(metadata) {
+        parse(value) {
+          const metadata = value as Record<string, unknown>;
           return { ...metadata, owner: metadata.owner ?? "maintainers" };
         },
       },
@@ -67,9 +76,11 @@ export default defineConfig({
 });
 ```
 
-The schema receives only custom metadata. It cannot change route, title, draft,
-or other reserved page fields. Returned values must be JSON-safe because the
-renderer passes them through a build-time virtual module.
+The schema receives only custom metadata and may provide `parse` or
+`parseAsync`, so a Zod schema works directly. The returned object is merged
+over the original metadata, so fields the schema omits are kept. It cannot set
+route, title, draft, or other reserved page fields. Returned values must be
+JSON-safe because the renderer passes them through a build-time virtual module.
 
 ## Read the content graph
 
@@ -85,9 +96,10 @@ const visiblePages = getCookbookCollection();
 const guide = getCookbookEntry("/guide");
 ```
 
-Queries return snapshots. Drafts are omitted from the collection by default;
-`getCookbookEntry()` can retrieve one by its exact route. The same API is
-available at `@tenphi/renderer/content` for renderer-only projects.
+Queries return snapshots. Drafts are omitted from the collection unless you
+call `getCookbookCollection({ includeDrafts: true })`; `getCookbookEntry()` can
+retrieve one by its exact route. The same API is available at
+`@tenphi/renderer/content` for renderer-only projects.
 
 Component overrides receive page data from `Astro.locals.cookbookRoute`,
 including the current entry, locale, navigation, table of contents, and head

package/docs/publishing.md

@@ -116,8 +116,9 @@ them as duplicates. See Google's
 
 ## Breadcrumb structured data
 
-`site.seo.breadcrumbs: true` emits a `BreadcrumbList` when at least two actual
-ancestor pages exist. Intermediate folders without pages are skipped. To describe
+`site.seo.breadcrumbs: true` emits a `BreadcrumbList` when the page has at least
+one actual ancestor page in its locale (the home page counts); the trail ends
+with the page itself. Intermediate folders without pages are skipped. To describe
 a different navigation journey, supply at least two `{name, url}` items in a page's
 `seo.breadcrumbs`. URLs must be absolute HTTP(S); the final URL must match that
 page's canonical. Set `seo.breadcrumbs: false` on a page to disable it.

package/docs/quality-checks.md

@@ -1,12 +1,13 @@
 ---
 title: Quality checks
-description: Validate a site, understand the consumer test matrix, and measure output budgets.
+description: Validate a documentation site, see which environments Cookbook supports, and review its output budgets.
 ---
 
-## For your documentation site
+## Check your documentation site
 
-Run `npm run validate` in a generated project: it checks the configuration and
-local files, builds the site, and validates the output. After deploying, run
+Run `npm run validate` in a generated project: it type-checks the project,
+checks the configuration and local files, builds the site, and validates the
+output. After deploying, run
 `npx @tenphi/cookbook check-build --url https://docs.example.com/` against the
 same build. See [CLI validation](./cli.md#check-the-built-site-and-deployment)
 for coverage and preview-host behavior.
@@ -15,35 +16,16 @@ Also review keyboard navigation, mobile layouts, and all four light/dark and
 normal/high-contrast combinations after changing styles. Automated accessibility
 checks supplement this review; they do not establish complete accessibility.
 
-## Cookbook's verification suite
+## Supported environments
 
-Repository contributors can run these checks after `pnpm build`:
-
-| Command                      | Coverage                                                                                     |
-| ---------------------------- | -------------------------------------------------------------------------------------------- |
-| `pnpm test`                  | Configuration, graph, rendering helpers, diagnostics, and interaction logic                  |
-| `pnpm check:locales`         | Real locale/fallback/navigation consumers                                                    |
-| `pnpm check:publishing-site` | Combined base paths, locales, versions, drafts, SEO, and agent Markdown                      |
-| `pnpm check:theming`         | Consumer components, colors, units, recipes, presets, overrides, and logos                   |
-| `pnpm check:fonts`           | Real Google variable/italic fonts, local fonts, and offline cache rebuild                    |
-| `pnpm check:plugins`         | Tested plugin contracts and actionable incompatibility failures                              |
-| `pnpm check:recipes`         | Public anatomy inventory and build-checked examples                                          |
-| `pnpm check:authoring`       | Custom highlighting, code groups, mobile contents, hero images, and OpenAPI                  |
-| `pnpm check:browser`         | Chromium keyboard/focus, search, copy actions, appearance, mobile navigation, and axe checks |
-| `pnpm check:install`         | Clean installation and build from packed artifacts, including lint/type exports              |
-| `pnpm check:benchmark`       | A generated 500-page corpus with 10,000 headings and code samples                            |
-
-Install the browser once with `pnpm exec playwright install chromium`.
-CI covers npm, pnpm, and Yarn installations, Node 22/24/26, and Linux, macOS,
-and Windows in representative combinations. Yarn uses its `node-modules` linker;
-Plug'n'Play is not covered. The weekly upstream canary installs the newest Astro
-version allowed by Cookbook's peer range and actually builds the packed consumer.
-Google Fonts checks run in that network-enabled canary. Published documentation
-is checked after deployment against its uploaded build artifact.
-
-The lint consumer uses TypeScript 6 for the typescript-eslint parser and the
-workspace TypeScript compiler for public API checks; typescript-eslint currently
-rejects the TypeScript 7 API. Runtime compilation and lint parsing are separate.
+Cookbook's CI covers npm, pnpm, and Yarn installations, Node 22/24/26, and
+Linux, macOS, and Windows in representative combinations. Yarn uses its
+`node-modules` linker; Plug'n'Play is not covered. A weekly upstream canary
+installs the newest Astro version allowed by Cookbook's peer range and builds
+a packed consumer site. The same network-enabled canary runs the real Google
+Fonts download check and a 1,000-page benchmark build. Cookbook's own
+published documentation is checked after deployment against its uploaded build
+artifact.
 
 ## Performance budgets and corpus measurements
 
@@ -55,8 +37,7 @@ router remain lazy. The initial JavaScript budget is 24 KiB.
 The checked reference output contains about 73 KB of fonts, 66 KB of images and
 icons, and a 181 KB shared stylesheet. The guide's first-party HTML, CSS, and
 initial JavaScript total about 40 KB when gzipped. Actual network transfers vary
-with hosting compression and caching. `node scripts/check-reference-budgets.mjs`
-prints current raw budgets and the gzip estimate; neither includes external
+with hosting compression and caching. None of these figures include external
 analytics.
 
 A local macOS / Node 22.22 run processed 500 pages with 10,000 headings in about
@@ -66,11 +47,6 @@ observations on one machine, not throughput guarantees. The full-build corpus
 uses explicit minimal navigation so the measurement is not dominated by repeating
 hundreds of sidebar links in every page.
 
-```sh
-COOKBOOK_BENCH_PAGES=1000 COOKBOOK_BENCH_BUILD=1 pnpm check:benchmark
-COOKBOOK_TEST_MANAGER=pnpm pnpm check:install
-COOKBOOK_TEST_UPSTREAM=1 pnpm check:install
-```
-
-Investigate regressions before changing a budget. CI retains browser traces on
-failure, and the benchmark reports graph timings, memory, and optional build time.
+Cookbook's own test suite, browser checks, and benchmark commands are described
+in the repository's
+[contributing guide](https://github.com/tenphi/cookbook/blob/main/CONTRIBUTING.md#verification-suite).

package/docs/recipes.md

@@ -1,21 +1,20 @@
 ---
-title: Configuration recipes
-description: Complete, build-checked configurations for common documentation tasks.
+title: Theme recipes
+description: Complete, build-checked configurations for branding, component styles, fonts, and shared themes.
 ---
 
-These are complete `docs.config.ts` files. Start with a generated Cookbook
-project, keep its `astro.config` integration, and replace the documentation
-configuration with one recipe. Add the files listed above each example.
-[Working examples](./examples.md) covers repository and npm source layouts;
-[configuration](./configuration.md) lists the available fields, while the
-[theme guide](./theme-and-components.md) explains the customization path.
+These are complete `docs.config.ts` files for common appearance changes. Start
+with a generated Cookbook project, keep its `astro.config` integration, and
+replace the documentation configuration with one recipe. Add the files listed
+above each example. Every recipe is type-checked and built by Cookbook's test
+suite.
 
-The repository's `pnpm check:recipes` extracts the marked examples below and in
-Working examples verbatim, type-checks them, builds actual consumer sites, and
-checks their output. Fixtures supply the documented content and local assets.
-Network-dependent Google font coverage runs separately in `check:fonts`.
+[Working examples](./examples.md) cover repository, npm, language, and preview
+layouts; the [theme guide](./theme-and-components.md) explains the
+customization path, and the [configuration reference](./configuration.md) lists
+every field.
 
-## Brand, logo, and round header controls
+## Brand, logo, and header control shape
 
 Put your artwork at `public/logo.svg`. Logo files use their intrinsic aspect
 ratio; the site title provides its label when the artwork is decorative.
@@ -30,15 +29,18 @@ export default defineDocsConfig({
   },
   theme: {
     brand: { from: "#d97706" },
-    tokens: { "$header-control-radius": "999px", $radius: "8px" },
+    tokens: { "$header-control-radius": "8px", $radius: "6px" },
     styles: { SearchResults: { Input: { radius: "12px" } } },
   },
 });
 ```
 
-The header token also covers the mobile sidebar close control. Copy buttons and
-page navigation keep the base radius. Built-in element overrides merge into the
-complete defaults. See the [named style anatomy](./component-styles.md).
+`$header-control-radius` replaces the default pill-shaped header buttons
+(`999px`) and also covers the mobile sidebar close control. `$radius` changes
+copy buttons, navigation items, and other content controls (default `8px`).
+Built-in element overrides merge into the complete defaults. See the
+[logo guide](./theme-and-components.md#logo-and-favicon) and the
+[named style anatomy](./component-styles.md).
 
 ## Built-in component styles
 
@@ -94,49 +96,31 @@ Cookbook downloads and self-hosts the required weights and italics at build time
 See [fonts](./fonts-and-typography.md#change-font-families) for caching,
 explicit ranges, styles, and remote delivery.
 
-## English and French
+## Share configuration and themes
 
-Create `docs/index.md`, `docs/guide.md`, `docs/fr/index.md`, and
-`docs/fr/guide.md`. Routes are `/`, `/guide`, `/fr`, and `/fr/guide`.
+A preset is an ordinary exported `DocsConfig` object:
 
-```ts cookbook-verify=locales
-import { defineDocsConfig } from "@tenphi/cookbook/config";
+```ts cookbook-verify=shared-theme
+import { defineDocsConfig, mergeDocsConfig } from "@tenphi/cookbook/config";
 
-export default defineDocsConfig({
-  site: { title: "Acme docs", url: "https://docs.example.com" },
-  content: { sources: [{ glob: "docs/**/*.md", base: "docs" }] },
-  locales: {
-    root: { label: "English", lang: "en" },
-    fr: { label: "Français" },
+const company = defineDocsConfig({
+  theme: {
+    brand: { from: "#315efb" },
+    tokens: { $radius: "8px" },
   },
-  defaultLocale: "root",
-  navigation: ["/", "/guide"],
-  translations: { fr: { appearance: "Présentation" } },
+  markdown: { rawHtml: "sanitize" },
 });
-```
-
-Navigation adapts to real translations. Missing translations use a real fallback
-in the language picker; they do not generate phantom routes or alternate links.
-
-## Preview publishing
 
-Set the preview's own URL and Astro `base` if hosted in a subdirectory. Serve
-private previews behind host authentication.
-
-```ts cookbook-verify=preview
-import { defineDocsConfig } from "@tenphi/cookbook/config";
-
-export default defineDocsConfig({
-  site: {
-    title: "Acme preview",
-    url: "https://preview.example.com",
-    seo: { index: false, copyPage: false },
-  },
-  tableOfContents: { mobile: true },
+export default mergeDocsConfig(company, {
+  site: { title: "Product docs" },
+  theme: { tokens: { "$content-width": "52rem" } },
 });
 ```
 
-Build, run `cookbook check-build`, deploy that output, then run
-`cookbook check-build --url https://preview.example.com/`. See
-[deployment](./deployment.md) for production metadata, host headers, and sitemap
-checks, and [troubleshooting](./troubleshooting.md) when a check fails.
+Each `theme.brand` or `theme.palette` color replaces the corresponding color in
+the preset. Supply the complete Glaze declaration for a color you override.
+
+Objects merge recursively, arrays replace, and inputs are not mutated. Tasty
+styles preserve their default values when adding conditional overrides. A preset
+can live in a shared workspace package. Component overrides remain partial Tasty
+objects and merge into Cookbook's complete base styles inside the renderer.

package/docs/ru/getting-started.md

@@ -63,8 +63,6 @@ Cookbook включает собственный рендерер Astro и ав
 
 ## Настройте сайт
 
-Начните с готовых [рецептов для фирменного стиля, логотипа и шрифтов](../recipes.md). Более глубокие изменения стилей и создание компонентов описаны в [правилах настройки](../customization-rules.md). Эти правила и ссылки на первоисточники также входят в установленный пакет Cookbook.
-
 Создайте `docs.config.ts` рядом с `astro.config.ts`:
 
 ```ts
@@ -83,9 +81,11 @@ export default defineDocsConfig({
 });
 ```
 
-В `theme.fonts` можно указать [Google Fonts по имени или собственные файлы шрифтов](../fonts-and-typography.md). Для типографики используйте `theme.presets`, для встроенных элементов — `theme.styles`, а для новых элементов — `defineComponent()` вместе с `theme.customStyles`. Начните с [руководства по теме](../theme-and-components.md); все настраиваемые части перечислены в [справочнике стилей компонентов](../component-styles.md).
+В `theme.fonts` можно указать [Google Fonts по имени или собственные файлы шрифтов](../fonts-and-typography.md#change-font-families). Для типографики используйте `theme.presets`, для встроенных элементов — `theme.styles`, а для новых элементов — `defineComponent()` вместе с `theme.customStyles`. Начните с [руководства по теме](../theme-and-components.md); все настраиваемые части перечислены в [справочнике стилей компонентов](../component-styles.md).
+
+Полные отправные точки собраны в [рецептах для фирменного стиля, логотипа и шрифтов](../recipes.md). Более глубокие изменения стилей и создание компонентов описаны в [правилах настройки](../customization-rules.md). Эти правила и ссылки на первоисточники также входят в установленный пакет Cookbook.
 
-Интеграция и CLI загружают одну и ту же конфигурацию. Поддерживаются `docs.config.ts`, `.mts`, `.js` и `.mjs` именно в таком порядке. Явный объект `config` в интеграции имеет приоритет; `configFile: false` отключает обнаружение файла. Для нестандартного расположения используйте `cookbook({ configFile: "./config/manual.ts" })` и `cookbook doctor --config ./config/manual.ts`.
+Интеграция и CLI загружают одну и ту же конфигурацию. Поддерживаются `docs.config.ts`, `.mts`, `.js` и `.mjs` именно в таком порядке. Явный объект `config` в интеграции имеет приоритет; `configFile: false` отключает обнаружение файла. Для нестандартного расположения используйте `cookbook({ configFile: "./config/manual.ts" })` и `cookbook doctor --config ./config/manual.ts`. Поскольку `root` указывается относительно каталога файла конфигурации, такому файлу нужен `root: ".."`, чтобы `README.md` и `docs/` по-прежнему читались из каталога приложения.
 
 ## Корневой каталог монорепозитория
 
@@ -106,4 +106,6 @@ npm run validate
 npm run preview
 ```
 
-Остальные руководства пока доступны на английском языке: [примеры](../examples.md), [компоненты для авторов](../authoring.mdx), [работа с ИИ-агентами](../ai-agents.md), [развёртывание](../deployment.md) и [обновление между версиями](../migration.md). Для полной конфигурации начните с [рецептов](../recipes.md). Если проверка завершилась ошибкой, см. [решение проблем](../troubleshooting.md).
+`validate` проверяет типы проекта, запускает предварительную проверку Cookbook, собирает сайт и проверяет результат. Если проект настроен вручную, добавьте скрипты из [описания команд CLI](../cli.md) или запустите `npx @tenphi/cookbook doctor`.
+
+Остальные руководства пока доступны на английском языке: [примеры](../examples.md), [компоненты для авторов](../authoring.mdx), [работа с ИИ-агентами](../ai-agents.md), [развёртывание](../deployment.md) и [обновление между версиями](../migration.md). Если проверка завершилась ошибкой, см. [решение проблем](../troubleshooting.md).

package/docs/ru/index.md

@@ -42,7 +42,7 @@ cd docs-site
 npm run dev
 ```
 
-Cookbook читает файлы на их текущем месте. Вы также можете [создать новый сайт](./getting-started.md), [описать именно те файлы, которые опубликованы в npm](./getting-started.md), или [добавить Cookbook в проект Astro](./getting-started.md).
+Cookbook читает файлы на их текущем месте. Вы также можете [создать новый сайт](./getting-started.md#создайте-первый-сайт), [описать именно те файлы, которые опубликованы в npm](./getting-started.md#опишите-опубликованный-npm-пакет), или [добавить Cookbook в проект Astro](./getting-started.md#добавьте-cookbook-в-существующий-проект-astro).
 
 ## Этот сайт служит примером
 

package/docs/site-navigation.md

@@ -21,49 +21,6 @@ navigation: {
 }
 ```
 
-## Client navigation
-
-Internal page links use client navigation over the generated static HTML. The
-router loads when an internal page link is hovered, focused, or clicked, so it
-does not add to the initial page download for readers who stay on one page. The
-current page stays visible while the next page and its styles load, then swaps
-without a full-page fade. Appearance preferences, sidebar expansion choices, and
-desktop sidebar scroll within the same navigation section are preserved. Article
-scroll resets to the top on page changes, including Back and Forward; links with
-fragments still navigate to their heading. The current page and its ancestors
-update from the destination markup. Mobile navigation and other open panels close.
-
-Cookbook enables Astro's built-in hover prefetching by default. Hovering over or
-focusing an internal link for about 80 ms downloads the destination HTML in the
-background. Moving across links briefly does not prefetch them, and repeated
-links to the same page share a prefetch. When the browser reports data-saving
-mode or a slow connection, Astro waits for tap intent instead.
-
-Prefetching warms the browser's HTTP cache. Static hosting should send cache
-headers such as `Cache-Control` or `ETag` so navigation can reuse the response;
-uncacheable responses may still be downloaded again on click. Browser and private
-session policies can also limit cache reuse. Destination stylesheets remain part
-of the router's preparation before the page swap.
-
-Set `prefetch: false` in `astro.config.mjs` to disable page prefetching while
-retaining client navigation. Cookbook preserves any explicit Astro `prefetch`
-configuration, including `prefetchAll: false` for selective prefetching. For a
-single link, use `data-astro-prefetch="false"` to opt out or
-`data-astro-prefetch` to opt in. See [Astro's prefetch guide](https://docs.astro.build/en/guides/prefetch/)
-for the supported strategies.
-
-Search keeps its query and loaded engine between pages in the same language,
-and closes when a result is followed. Language changes initialize the translated
-search interface. External links, downloads, modified clicks, and links marked
-`data-astro-reload` keep normal browser behavior. Without JavaScript, page links
-use normal document navigation.
-
-Custom browser scripts should attach behavior through custom-element lifecycle
-callbacks or initialize on `astro:page-load`; bundled scripts are not rerun on
-every client navigation. The router and appearance initialization belong to the
-common page shell and remain available with replacement Header, Head, and
-PageFrame components.
-
 ## Search
 
 The production build creates a local Pagefind index. Readers can select Search
@@ -89,8 +46,8 @@ the tab's URL prefix when listed in that tab's `items`.
 
 Top-level groups keep their headings and direct links visible. Deeper groups
 open on click or keyboard activation, and the current page's ancestors open on
-arrival. A linked group header selects its page before toggling when that page
-is already selected. Explicit expansion choices are remembered for the browser
+arrival. Clicking a linked group header first selects its page and opens the
+group; once that page is selected, clicking the header toggles the group. Explicit expansion choices are remembered for the browser
 tab. Only the current page is highlighted.
 
 On narrow screens, the active sidebar moves into a drawer. It includes the
@@ -113,7 +70,7 @@ navigation: [
       "/deploying",
     ],
   },
-];
+],
 ```
 
 To keep the badge with its page, set it in frontmatter instead:
@@ -128,7 +85,7 @@ inherit the page's badge. An explicit navigation `badge` overrides frontmatter;
 use `badge: ""` to hide an inherited badge. Badges are plain text, including
 characters such as `<`, and do not change pagination labels.
 
-Badges use the brand-derived `accentText` and `accentSurfaceSubtle` palette roles
+Badges use the brand-derived `accent-text` and `accent-surface-subtle` palette roles
 in every color scheme and contrast mode. Customize their appearance with a
 partial [component style override](./component-styles.md):
 
@@ -164,3 +121,46 @@ exists and fall back to a real language or version home when it does not.
 Only available translations appear in alternate-language metadata. See the
 [language](./configuration.md#languages) and
 [version](./configuration.md#site) configuration examples.
+
+## Client navigation
+
+Internal page links use client navigation over the generated static HTML. The
+router loads when an internal page link is hovered, focused, or clicked, so it
+does not add to the initial page download for readers who stay on one page. The
+current page stays visible while the next page and its styles load, then swaps
+without a full-page fade. Appearance preferences, sidebar expansion choices, and
+desktop sidebar scroll within the same navigation section are preserved. Article
+scroll resets to the top on page changes, including Back and Forward; links with
+fragments still navigate to their heading. The current page and its ancestors
+update from the destination markup. Mobile navigation and other open panels close.
+
+Cookbook enables Astro's built-in hover prefetching by default. Hovering over or
+focusing an internal link for about 80 ms downloads the destination HTML in the
+background. Moving across links briefly does not prefetch them, and repeated
+links to the same page share a prefetch. When the browser reports data-saving
+mode or a slow connection, Astro waits for tap intent instead.
+
+Prefetching warms the browser's HTTP cache. Static hosting should send cache
+headers such as `Cache-Control` or `ETag` so navigation can reuse the response;
+uncacheable responses may still be downloaded again on click. Browser and private
+session policies can also limit cache reuse. Destination stylesheets remain part
+of the router's preparation before the page swap.
+
+Set `prefetch: false` in `astro.config.ts` to disable page prefetching while
+retaining client navigation. Cookbook preserves any explicit Astro `prefetch`
+configuration, including `prefetchAll: false` for selective prefetching. For a
+single link, use `data-astro-prefetch="false"` to opt out or
+`data-astro-prefetch` to opt in. See [Astro's prefetch guide](https://docs.astro.build/en/guides/prefetch/)
+for the supported strategies.
+
+Search keeps its query and loaded engine between pages in the same language,
+and closes when a result is followed. Language changes initialize the translated
+search interface. External links, downloads, modified clicks, and links marked
+`data-astro-reload` keep normal browser behavior. Without JavaScript, page links
+use normal document navigation.
+
+Custom browser scripts should attach behavior through custom-element lifecycle
+callbacks or initialize on `astro:page-load`; bundled scripts are not rerun on
+every client navigation. The router and appearance initialization belong to the
+common page shell and remain available with replacement Header, Head, and
+PageFrame components.