@tenphi/cookbook 0.23.0 → 0.25.0

package/docs/component-styles.md

@@ -214,7 +214,7 @@ it stays complete when a surface changes.
 
 #### Page shell
 
-* `Document`: `All`, `BlockSpacing`, `Body`, `Control`, `Pointer`, `ResponsiveWidth`, `ResponsiveHeight`, `Hidden`, `PrintHidden`, `DesktopBlock`, `DesktopFlex`, `ScreenReaderOnly`, `Strong`, `Link`, `NarrowBlock`, `MobileBlock`, `Code`, `FocusRing`, `CurrentLink`, `SearchOpen`
+* `Document`: `All`, `BlockSpacing`, `Body`, `Control`, `Pointer`, `ResponsiveWidth`, `ResponsiveHeight`, `Hidden`, `PrintHidden`, `DesktopBlock`, `DesktopFlex`, `ScreenReaderOnly`, `RouteAnnouncer`, `Strong`, `Link`, `NarrowBlock`, `MobileBlock`, `Code`, `FocusRing`, `CurrentLink`, `SearchOpen`
 * `Layout`: `Islands`
 * `PageFrame`: `MainFrame`, `SidebarFrame`, `Columns`
 * `MainPane`: None

package/docs/quality-checks.md

@@ -49,10 +49,12 @@ rejects the TypeScript 7 API. Runtime compilation and lint parsing are separate.
 
 The reference build enforces separate limits for initial page JavaScript,
 lazy search assets, font files, images, and extracted Tasty CSS. A default guide
-currently loads about 9 KB of first-party JavaScript initially; search is lazy.
+currently loads about 22 KB of first-party JavaScript initially (about 10 KB
+gzipped), including Astro's built-in hover prefetching; search and the client
+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 189 KB shared stylesheet. The guide's first-party HTML, CSS, and
-initial JavaScript total about 33 KB when gzipped. Actual network transfers vary
+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
 analytics.

package/docs/site-navigation.md

@@ -21,6 +21,49 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/cookbook",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Repository-native static documentation for Astro",
   "type": "module",
   "keywords": [
@@ -68,8 +68,8 @@
   "author": "Andrey Yamanov",
   "license": "MIT",
   "dependencies": {
-    "@tenphi/docs": "0.23.0",
-    "@tenphi/renderer": "0.23.0"
+    "@tenphi/docs": "0.25.0",
+    "@tenphi/renderer": "0.25.0"
   },
   "peerDependencies": {
     "astro": "^7.3.2"