dinou 7.0.0 → 7.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # **Dinou**
2
2
 
3
- [![Documentation](https://img.shields.io/badge/docs-dinou.dev-blue?style=flat-square)](https://dinou.dev) [![Version](https://img.shields.io/badge/version-7.0.0-orange?style=flat-square)](https://www.npmjs.com/package/dinou)
3
+ [![Documentation](https://img.shields.io/badge/docs-dinou.dev-blue?style=flat-square)](https://dinou.dev) [![Version](https://img.shields.io/badge/version-7.2.0-orange?style=flat-square)](https://www.npmjs.com/package/dinou)
4
4
 
5
5
  ### **Full-Stack React 19 Framework**
6
6
 
@@ -152,60 +152,60 @@ The ejectable React 19 framework built on web standards. Build full-stack applic
152
152
  - [6.2. Governance APIs (validateParams & allowISG)](#62-governance-apis-validateparams--allowisg)
153
153
  - [7. Complete Rendering Strategies Matrix](#7-complete-rendering-strategies-matrix)
154
154
  - [Server Functions ("use server")](#server-functions-use-server)
155
- - [Overview & "use server" Directive](#overview-use-server-directive)
155
+ - [Overview & "use server" Directive](#overview--use-server-directive)
156
156
  - [1. Returning Live React Components (UI Streaming)](#1-returning-live-react-components-ui-streaming)
157
- - [2. Server Actions & Form Mutations](#2-server-actions-form-mutations)
157
+ - [2. Server Actions & Form Mutations](#2-server-actions--form-mutations)
158
158
  - [2.1. Server Actions in Forms](#21-server-actions-in-forms)
159
- - [2.2. React 19 Hooks: useActionState & useFormStatus](#22-react-19-hooks-useactionstate-useformstatus)
159
+ - [2.2. React 19 Hooks: useActionState & useFormStatus](#22-react-19-hooks-useactionstate--useformstatus)
160
160
  - [2.3. Optimistic Updates with useOptimistic](#23-optimistic-updates-with-useoptimistic)
161
- - [3. Request Context, Cookies & Headers (getContext)](#3-request-context-cookies-headers-getcontext)
162
- - [3.1. Reading Query, Headers & Cookies](#31-reading-query-headers-cookies)
163
- - [3.2. Setting & Clearing Cookies](#32-setting-clearing-cookies)
161
+ - [3. Request Context, Cookies & Headers (getContext)](#3-request-context-cookies--headers-getcontext)
162
+ - [3.1. Reading Query, Headers & Cookies](#31-reading-query-headers--cookies)
163
+ - [3.2. Setting & Clearing Cookies](#32-setting--clearing-cookies)
164
164
  - [4. Redirections (redirect)](#4-redirections-redirect)
165
165
  - [4.1. The 4 Execution Contexts (HTTP 302 vs. Client Transition)](#41-the-4-execution-contexts-http-302-vs-client-transition)
166
166
  - [4.2. Universal Redirection Matrix](#42-universal-redirection-matrix)
167
167
  - [On-Demand Revalidation](#on-demand-revalidation)
168
- - [Overview & Multi-Tier Architecture](#overview-multi-tier-architecture)
168
+ - [Overview & Multi-Tier Architecture](#overview--multi-tier-architecture)
169
169
  - [1. revalidatePage (Surgical Page Invalidation)](#1-revalidatepage-surgical-page-invalidation)
170
170
  - [1.1. Usage in Server Functions](#11-usage-in-server-functions)
171
- - [2. revalidatePath (Route & Segment Purge)](#2-revalidatepath-route-segment-purge)
172
- - [2.1. Cascading Revalidation ({ cascade: true })](#21-cascading-revalidation-cascade-true)
173
- - [3. Granularity & Path Resolution (Page vs Segment)](#3-granularity-path-resolution-page-vs-segment)
171
+ - [2. revalidatePath (Route & Segment Purge)](#2-revalidatepath-route--segment-purge)
172
+ - [2.1. Cascading Revalidation ({ cascade: true })](#21-cascading-revalidation--cascade-true)
173
+ - [3. Granularity & Path Resolution (Page vs Segment)](#3-granularity--path-resolution-page-vs-segment)
174
174
  - [3.1. revalidatePage vs revalidatePath](#31-revalidatepage-vs-revalidatepath)
175
- - [3.2. Absolute & Relative Route Paths](#32-absolute-relative-route-paths)
175
+ - [3.2. Absolute & Relative Route Paths](#32-absolute--relative-route-paths)
176
176
  - [4. revalidateTag (Cross-Cutting Invalidation)](#4-revalidatetag-cross-cutting-invalidation)
177
177
  - [4.1. Tag Assignment (getCacheTags)](#41-tag-assignment-getcachetags)
178
178
  - [4.2. Targeted Resolution (Layout vs Page vs Slot)](#42-targeted-resolution-layout-vs-page-vs-slot)
179
179
  - [4.3. Golden Rules of Invalidation](#43-golden-rules-of-invalidation)
180
180
  - [4.4. Invalidating <DinouCacheSlot> Subtrees](#44-invalidating-dinoucacheslot-subtrees)
181
- - [5. Client-Side Surgical Revalidation & Router Caching](#5-client-side-surgical-revalidation-router-caching)
182
- - [5.1. The Router Caches (pageCache & layoutCache)](#51-the-router-caches-pagecache-layoutcache)
181
+ - [5. Client-Side Surgical Revalidation & Router Caching](#5-client-side-surgical-revalidation--router-caching)
182
+ - [5.1. The Router Caches (pageCache & layoutCache)](#51-the-router-caches-pagecache--layoutcache)
183
183
  - [5.2. Bypassing Client Cache with <Link fresh>](#52-bypassing-client-cache-with-link-fresh)
184
- - [5.3. router.refresh() & Layout Invalidation](#53-routerrefresh-layout-invalidation)
185
- - [5.4. refreshSlot & router.refreshSlot](#54-refreshslot-routerrefreshslot)
184
+ - [5.3. router.refresh() & Layout Invalidation](#53-routerrefresh--layout-invalidation)
185
+ - [5.4. refreshSlot & router.refreshSlot](#54-refreshslot--routerrefreshslot)
186
186
  - [6. Pluggable Storage Adapters](#6-pluggable-storage-adapters)
187
187
  - [6.1. Why Adapters Matter for Revalidation](#61-why-adapters-matter-for-revalidation)
188
- - [6.2. Supported Storage Adapters & Configuration](#62-supported-storage-adapters-configuration)
188
+ - [6.2. Supported Storage Adapters & Configuration](#62-supported-storage-adapters--configuration)
189
189
  - [7. Webhook Integrations (Headless CMS)](#7-webhook-integrations-headless-cms)
190
190
  - [8. Strategy Comparison Matrix](#8-strategy-comparison-matrix)
191
191
  - [8.1. Server-Side Invalidation Mechanisms](#81-server-side-invalidation-mechanisms)
192
192
  - [8.2. Client-Side Router Refresh Mechanisms](#82-client-side-router-refresh-mechanisms)
193
193
  - [Data Fetching: The 13 Strategies](#data-fetching-the-13-strategies)
194
194
  - [Overview: The 13-Strategy Architecture](#overview-the-13-strategy-architecture)
195
- - [Data Fetching & Rendering Strategies Matrix](#data-fetching-rendering-strategies-matrix)
195
+ - [Data Fetching & Rendering Strategies Matrix](#data-fetching--rendering-strategies-matrix)
196
196
  - [1. RSC Direct await (SSG)](#1-rsc-direct-await-ssg)
197
197
  - [2. RSC Direct await (Dynamic SSR)](#2-rsc-direct-await-dynamic-ssr)
198
198
  - [3. RSC with <Suspense> (SSG)](#3-rsc-with-suspense-ssg)
199
199
  - [4. RSC with <Suspense> (Dynamic Streaming SSR)](#4-rsc-with-suspense-dynamic-streaming-ssr)
200
- - [5. RSC + <Suspense> + <DinouCacheSlot> (Static SSG / Asymmetric ISR)](#5-rsc-suspense-dinoucacheslot-static-ssg-asymmetric-isr)
201
- - [6. RSC + <Suspense> + <DinouCacheSlot> (Dynamic Micro-ISR)](#6-rsc-suspense-dinoucacheslot-dynamic-micro-isr)
200
+ - [5. RSC + <Suspense> + <DinouCacheSlot> (Static SSG / Asymmetric ISR)](#5-rsc--suspense--dinoucacheslot-static-ssg--asymmetric-isr)
201
+ - [6. RSC + <Suspense> + <DinouCacheSlot> (Dynamic Micro-ISR)](#6-rsc--suspense--dinoucacheslot-dynamic-micro-isr)
202
202
  - [7. RSC with <Suspense> (PPR Hybrid)](#7-rsc-with-suspense-ppr-hybrid)
203
- - [8. PPR + <DinouCacheSlot> (Peak Performance Synergy)](#8-ppr-dinoucacheslot-peak-performance-synergy)
204
- - [9. RSC Promise ➔ Client use() (React 19)](#9-rsc-promise-client-use-react-19)
203
+ - [8. PPR + <DinouCacheSlot> (Peak Performance Synergy)](#8-ppr--dinoucacheslot-peak-performance-synergy)
204
+ - [9. RSC Promise ➔ Client use() (React 19)](#9-rsc-promise--client-use-react-19)
205
205
  - [10. Client-First getProps (SSG)](#10-client-first-getprops-ssg)
206
206
  - [11. Client-First getProps (Dynamic SSR)](#11-client-first-getprops-dynamic-ssr)
207
207
  - [12. Client Calling Server Function (Initial Mount - Dynamic RPC)](#12-client-calling-server-function-initial-mount---dynamic-rpc)
208
- - [13. Client Server Functions (User Actions & Mutations)](#13-client-server-functions-user-actions-mutations)
208
+ - [13. Client Server Functions (User Actions & Mutations)](#13-client-server-functions-user-actions--mutations)
209
209
  - [Architectural Decision Guide](#architectural-decision-guide)
210
210
  - [The Dinou Pattern](#the-dinou-pattern)
211
211
  - [The Concept & Architecture](#the-concept--architecture)
@@ -339,89 +339,68 @@ The ejectable React 19 framework built on web standards. Build full-stack applic
339
339
  - [2. Extending the Bundler Pipeline](#2-extending-the-bundler-pipeline)
340
340
  - [Best Practices for Ejected Projects](#best-practices-for-ejected-projects)
341
341
  - [Complete API Reference](#complete-api-reference)
342
- - [1. Components (dinou)](#components)
342
+ - [1. Components (dinou)](#1-components-dinou)
343
343
  - [`<Link>`](#link)
344
344
  - [`<ClientRedirect>`](#clientredirect)
345
- - [2. Hooks & Navigation (dinou)](#hooks-navigation)
345
+ - [2. Hooks & Navigation (dinou)](#2-hooks--navigation-dinou)
346
346
  - [redirect()](#redirect)
347
347
  - [useSearchParams()](#usesearchparams)
348
- - [in Server Components](#usesearchparams-server)
349
- - [in Client Components](#usesearchparams-client)
350
348
  - [usePathname()](#usepathname)
351
- - [in Server Components](#usepathname-server)
352
- - [in Client Components](#usepathname-client)
353
349
  - [useRouter()](#userouter)
354
- - [Methods Reference](#userouter-methods)
355
- - [Client Cache & Options](#userouter-caching)
356
- - [Production Patterns](#userouter-examples)
357
350
  - [refreshSlot()](#refreshslot)
358
- - [Parameters & Wildcard](#refreshslot-parameters)
359
- - [Targeted Revalidation](#refreshslot-architecture)
360
- - [Production Patterns](#refreshslot-examples)
361
351
  - [useNavigationLoading()](#usenavigationloading)
362
- - [Trigger Events & SSR](#usenavigationloading-behavior)
363
- - [Non-Blocking Transitions](#usenavigationloading-architecture)
364
- - [Production Indicators](#usenavigationloading-examples)
365
- - [3. Type-Safe Routing (dinou)](#type-safe-routing)
366
- - [`PageProps<T>`](#pageprops)
367
- - [`LayoutProps<T>`](#layoutprops)
368
- - [`ErrorProps<T>`](#errorprops)
369
- - [PageFunctions & LayoutFunctions](#pagefunctions)
370
- - [`RouteParams<T>`](#routeparams)
352
+ - [3. Type-Safe Routing (dinou)](#3-type-safe-routing-dinou)
353
+ - [`PageProps`](#pageprops)
354
+ - [`LayoutProps`](#layoutprops)
355
+ - [`ErrorProps`](#errorprops)
356
+ - [PageFunctions & LayoutFunctions](#pagefunctions--layoutfunctions)
357
+ - [`RouteParams`](#routeparams)
371
358
  - [DinouRoute](#dinouroute)
372
359
  - [DinouRoutePattern](#dinouroutepattern)
373
- - [4. Server Context & Config (dinou)](#server-context-config)
360
+ - [4. Server Context & Config (dinou)](#4-server-context--config-dinou)
374
361
  - [getContext()](#getcontext)
375
- - [Request & Response Store](#getcontext-store)
376
- - [Production Patterns](#getcontext-examples)
377
362
  - [defineConfig()](#defineconfig)
378
- - [Configuration Schema](#defineconfig-schema)
379
- - [Production Configuration](#defineconfig-examples)
380
363
  - [DinouPlugin](#dinouplugin)
381
- - [Lifecycle & Early Exit](#dinouplugin-lifecycle)
382
- - [Production Plugins](#dinouplugin-examples)
383
- - [5. Server Cache & Revalidation (dinou/server)](#server-cache-revalidation)
364
+ - [5. Server Cache & Revalidation (dinou/server)](#5-server-cache--revalidation-dinouserver)
384
365
  - [revalidatePage()](#revalidatepage)
385
366
  - [revalidatePath()](#revalidatepath)
386
367
  - [revalidateTag()](#revalidatetag)
387
368
  - [`<DinouCacheSlot>`](#dinoucacheslot)
388
- - [Props & Micro-ISR](#dinoucacheslot-props)
389
- - [Production Slot Patterns](#dinoucacheslot-examples)
390
- - [6. Storage Adapters (dinou/server)](#storage-adapters)
391
- - [Built-In Adapters](#storage-adapters-list)
392
- - [StorageAdapter Interface](#storage-adapters-interface)
393
- - [Custom Storage Engine](#storage-adapters-custom)
394
- - [7. Route Lifecycles & Config](#route-segment-contracts)
369
+ - [6. Storage Adapters (dinou/server)](#6-storage-adapters-dinouserver)
370
+ - [Built-In Adapters](#built-in-adapters)
371
+ - [StorageAdapter Interface](#storageadapter-interface)
372
+ - [Custom Storage Engine](#custom-storage-engine)
373
+ - [7. Route Lifecycles & Config](#7-route-lifecycles--config)
395
374
  - [getProps()](#getprops)
396
- - [revalidate](#revalidate-config)
397
- - [ppr](#ppr-config)
375
+ - [revalidate](#revalidate)
376
+ - [ppr](#ppr)
398
377
  - [getCacheTags](#getcachetags)
399
378
  - [getStaticPaths](#getstaticpaths)
400
379
  - [allowISG](#allowisg)
401
380
  - [validateParams()](#validateparams)
402
- - [⚡ Dinou Complete Cheatsheet](#cheatsheet)
403
- - [1. File Conventions](#file-conventions)
404
- - [Route Components & Lifecycles](#route-components)
405
- - [Layout Control Flags](#layout-flags)
406
- - [Route Escaping (_folder)](#route-escaping)
407
- - [2. Route Syntax & Types](#route-syntax)
408
- - [Route Patterns & Inferred Params](#route-patterns)
409
- - [Type-Safe Routing Helpers](#type-helpers)
410
- - [3. Server Lifecycle Contracts](#server-contracts)
411
- - [Exported Contracts Table](#lifecycle-contracts)
412
- - [Revalidation Modes (SSR, ISR, SSG)](#revalidate-modes)
413
- - [4. Client Navigation & Hooks](#navigation-hooks)
414
- - [Link & Redirection](#client-primitives)
415
- - [Router & Navigation Hooks](#location-hooks)
416
- - [5. Server Primitives & Cache](#server-primitives)
417
- - [getContext & DinouCacheSlot](#context-and-slots)
418
- - [On-Demand Invalidation](#cache-invalidation)
419
- - [6. Decision Matrix: When to Use What](#decision-matrix)
420
- - [Cache Invalidation Matrix](#matrix-cache)
421
- - [Redirection Strategy Matrix](#matrix-redirects)
422
- - [Route Parameter Access Matrix](#matrix-params)
423
- - [📜 Changelog](#changelog)
424
- - [📄 License](#license)
381
+ - [Dinou Complete Cheatsheet](#dinou-complete-cheatsheet)
382
+ - [1. File Conventions](#1-file-conventions-cheatsheet)
383
+ - [Route Components & Lifecycles](#route-components--lifecycles)
384
+ - [Layout Control Flags (Empty Files)](#layout-control-flags-empty-files)
385
+ - [Route Escaping (`_prefix`)](#route-escaping-_prefix)
386
+ - [2. Route Syntax & Types](#2-route-syntax--types)
387
+ - [Route Patterns & Inferred Params](#route-patterns--inferred-params)
388
+ - [Type-Safe Routing Helpers (`dinou`)](#type-safe-routing-helpers-dinou)
389
+ - [3. Server Lifecycle Contracts](#3-server-lifecycle-contracts)
390
+ - [Exported Contracts Table](#exported-contracts-table)
391
+ - [Revalidation Modes (SSR vs ISR vs SSG)](#revalidation-modes-ssr-vs-isr-vs-ssg)
392
+ - [4. Client Navigation & Hooks](#4-client-navigation--hooks)
393
+ - [Link & Redirection Primitives](#link--redirection-primitives)
394
+ - [Router & Navigation Hooks](#router--navigation-hooks)
395
+ - [5. Server Primitives & Cache](#5-server-primitives--cache)
396
+ - [getContext & DinouCacheSlot](#getcontext--dinoucacheslot)
397
+ - [On-Demand Cache Invalidation (`dinou/server`)](#on-demand-cache-invalidation-dinouserver)
398
+ - [6. Decision Matrix: When to Use What](#6-decision-matrix-when-to-use-what)
399
+ - [Cache Invalidation: Which method should you call?](#cache-invalidation-which-method-should-you-call)
400
+ - [Redirection: Which redirection strategy should you use?](#redirection-which-redirection-strategy-should-you-use)
401
+ - [Route Parameter Access: Where should you read route data?](#route-parameter-access-where-should-you-read-route-data)
402
+ - [Changelog](#changelog)
403
+ - [License](#license)
425
404
 
426
405
 
427
406
  ## Getting Started
@@ -601,7 +580,7 @@ Add the standard Dinou scripts to your `package.json` to control development, mu
601
580
  }
602
581
  ```
603
582
 
604
- > **Note:** For the complete catalog of targeted platform cross-compilation scripts (such as Windows, macOS, Linux ARM/x64), see the [Complete CLI Scripts Catalog](#complete-cli-scripts-catalog-100-scripts-reference).
583
+ > **Note:** For the complete catalog of targeted platform cross-compilation scripts (such as Windows, macOS, Linux ARM/x64), see the [Complete CLI Scripts Catalog](#complete-dinou-v7-scripts-matrix).
605
584
 
606
585
  #### 5. Configure .gitignore
607
586
 
@@ -649,7 +628,7 @@ npm run dev:rollup # Dedicated Rollup in-memory engine
649
628
  npm run dev:webpack # Dedicated Webpack engine
650
629
  ```
651
630
 
652
- For advanced compiler tuning, custom plugins, and SWC options, visit the [Bundlers Guide](#-bundlers--running-the-app).
631
+ For advanced compiler tuning, custom plugins, and SWC options, visit the [Bundlers Guide](#bundlers--build-tooling).
653
632
 
654
633
  #### First-Class Multi-Runtime Targets
655
634
 
@@ -674,7 +653,7 @@ Compile your application for any execution environment without altering componen
674
653
  ```
675
654
  Pre-rendered HTML and RSC Flight payloads output directly to `out/`.
676
655
 
677
- For complete deployment guides, Docker setups, and cloud hosting instructions, see the [Deployment Guide](#-deployment-guide).
656
+ For complete deployment guides, Docker setups, and cloud hosting instructions, see the [Deployment Guide](#deployment-guide).
678
657
 
679
658
  ## Routing & Layouts
680
659
 
@@ -6454,7 +6433,7 @@ And confirm your `tsconfig.json` includes the reference:
6454
6433
 
6455
6434
  ### Extending Custom Formats (Eject)
6456
6435
 
6457
- If your application requires specialized binary formats (e.g. `.hdr`, `.glb`, `.gltf` for 3D graphics, or `.wasm`), you can [eject Dinou](#-eject-dinou) to take full ownership of the pipeline.
6436
+ If your application requires specialized binary formats (e.g. `.hdr`, `.glb`, `.gltf` for 3D graphics, or `.wasm`), you can [eject Dinou](#eject-dinou) to take full ownership of the pipeline.
6458
6437
 
6459
6438
  In an ejected project, simply add your custom extensions to the array in `dinou/core/asset-extensions.js`:
6460
6439
 
@@ -7916,13 +7895,11 @@ Explore all exports across `dinou`, `dinou/server`, and route lifecycle contract
7916
7895
 
7917
7896
  ### 1. Components (`dinou`)
7918
7897
 
7919
- <a id="components"></a>
7920
7898
 
7921
7899
  Declarative universal and client components exported directly from `dinou`.
7922
7900
 
7923
7901
  ---
7924
7902
 
7925
- <a id="link"></a>
7926
7903
 
7927
7904
  #### `<Link>`
7928
7905
 
@@ -8057,7 +8034,6 @@ export default function SettingsSubNav() {
8057
8034
 
8058
8035
  ---
8059
8036
 
8060
- <a id="clientredirect"></a>
8061
8037
 
8062
8038
  #### `<ClientRedirect>`
8063
8039
 
@@ -8145,13 +8121,11 @@ export function PageB({ isAllowed }: { isAllowed: boolean }) {
8145
8121
 
8146
8122
  ### 2. Hooks & Navigation (`dinou`)
8147
8123
 
8148
- <a id="hooks-navigation"></a>
8149
8124
 
8150
8125
  Universal and client navigation hooks exported directly from `dinou`.
8151
8126
 
8152
8127
  ---
8153
8128
 
8154
- <a id="redirect"></a>
8155
8129
 
8156
8130
  #### `redirect()`
8157
8131
 
@@ -8341,7 +8315,6 @@ export default defineConfig({
8341
8315
 
8342
8316
  ---
8343
8317
 
8344
- <a id="usesearchparams"></a>
8345
8318
 
8346
8319
  #### `useSearchParams()`
8347
8320
 
@@ -8349,7 +8322,6 @@ A dual-nature hook that provides access to the current URL's query parameters. W
8349
8322
 
8350
8323
  ##### in Server Components
8351
8324
 
8352
- <a id="usesearchparams-server"></a>
8353
8325
 
8354
8326
  In Server Components, `useSearchParams()` resolves synchronously from the incoming HTTP request context via `AsyncLocalStorage`. It introduces **zero client bundle overhead** and eliminates props drilling across nested server components.
8355
8327
 
@@ -8398,7 +8370,6 @@ export default async function ProductCatalog() {
8398
8370
 
8399
8371
  ##### in Client Components
8400
8372
 
8401
- <a id="usesearchparams-client"></a>
8402
8373
 
8403
8374
  In Client Components, `useSearchParams()` is a reactive hook returning a `URLSearchParams` object. Whenever the URL changes (via `router.push()`, `<Link>`, or browser history), components re-render with updated values while preserving local state.
8404
8375
 
@@ -8452,7 +8423,6 @@ export default function SearchFilter() {
8452
8423
 
8453
8424
  ---
8454
8425
 
8455
- <a id="usepathname"></a>
8456
8426
 
8457
8427
  #### `usePathname()`
8458
8428
 
@@ -8460,7 +8430,6 @@ A dual-nature hook that provides access to the current URL pathname. Works in bo
8460
8430
 
8461
8431
  ##### in Server Components
8462
8432
 
8463
- <a id="usepathname-server"></a>
8464
8433
 
8465
8434
  In Server Components, `usePathname()` resolves synchronously from the active HTTP request context. It adds **0 KB** to the client JavaScript bundle.
8466
8435
 
@@ -8499,7 +8468,6 @@ export default async function ServerHeader() {
8499
8468
 
8500
8469
  ##### in Client Components
8501
8470
 
8502
- <a id="usepathname-client"></a>
8503
8471
 
8504
8472
  In Client Components, `usePathname()` is a reactive hook that provides the current browser URL pathname and triggers re-renders on route changes.
8505
8473
 
@@ -8541,7 +8509,6 @@ export function NavLink({ href, children, exact = false }: NavLinkProps) {
8541
8509
 
8542
8510
  ---
8543
8511
 
8544
- <a id="userouter"></a>
8545
8512
 
8546
8513
  #### `useRouter()`
8547
8514
 
@@ -8549,7 +8516,6 @@ The core programmatic navigation hook for Client Components. Provides programmat
8549
8516
 
8550
8517
  ##### Methods Reference
8551
8518
 
8552
- <a id="userouter-methods"></a>
8553
8519
 
8554
8520
  | Method | Signature | Description |
8555
8521
  | :--- | :--- | :--- |
@@ -8562,7 +8528,6 @@ The core programmatic navigation hook for Client Components. Provides programmat
8562
8528
 
8563
8529
  ##### Client Cache & Options
8564
8530
 
8565
- <a id="userouter-caching"></a>
8566
8531
 
8567
8532
  | Option | Type | Default | Description |
8568
8533
  | :--- | :--- | :--- | :--- |
@@ -8576,7 +8541,6 @@ The core programmatic navigation hook for Client Components. Provides programmat
8576
8541
 
8577
8542
  ##### Production Patterns
8578
8543
 
8579
- <a id="userouter-examples"></a>
8580
8544
 
8581
8545
  ```tsx
8582
8546
  // src/components/create-product-form.tsx (Client Component)
@@ -8620,7 +8584,6 @@ export function CreateProductForm() {
8620
8584
 
8621
8585
  ---
8622
8586
 
8623
- <a id="refreshslot"></a>
8624
8587
 
8625
8588
  #### `refreshSlot()`
8626
8589
 
@@ -8628,7 +8591,6 @@ Imperative client function enabling surgical on-demand revalidation of isolated
8628
8591
 
8629
8592
  ##### Parameters & Wildcard
8630
8593
 
8631
- <a id="refreshslot-parameters"></a>
8632
8594
 
8633
8595
  | Parameter | Type | Default | Description |
8634
8596
  | :--- | :--- | :--- | :--- |
@@ -8637,7 +8599,6 @@ Imperative client function enabling surgical on-demand revalidation of isolated
8637
8599
 
8638
8600
  ##### Targeted Revalidation Architecture
8639
8601
 
8640
- <a id="refreshslot-architecture"></a>
8641
8602
 
8642
8603
  - **Surgical Component Updates:** Unlike full route reloads, `refreshSlot()` communicates directly with the specific mounted `<DinouCacheSlot>` sub-tree. Parent layouts and sibling components are untouched.
8643
8604
  - **Client vs. Server Revalidation:** Server functions (`revalidateTag`, `revalidatePath`) purge cached storage records on the backend. `refreshSlot()` actively pulls and updates the live rendered UI in the user's browser session.
@@ -8645,7 +8606,6 @@ Imperative client function enabling surgical on-demand revalidation of isolated
8645
8606
 
8646
8607
  ##### Production Patterns
8647
8608
 
8648
- <a id="refreshslot-examples"></a>
8649
8609
 
8650
8610
  ```typescript
8651
8611
  // src/services/realtime-socket.ts (Pure TypeScript / Non-React)
@@ -8690,7 +8650,6 @@ export function DashboardToolbar() {
8690
8650
 
8691
8651
  ---
8692
8652
 
8693
- <a id="usenavigationloading"></a>
8694
8653
 
8695
8654
  #### `useNavigationLoading()`
8696
8655
 
@@ -8698,7 +8657,6 @@ Reactive Client Hook that returns `true` whenever a page navigation, history tra
8698
8657
 
8699
8658
  ##### Trigger Events & SSR
8700
8659
 
8701
- <a id="usenavigationloading-behavior"></a>
8702
8660
 
8703
8661
  | Navigation Source | Trigger API | Toggles Loading? | Details |
8704
8662
  | :--- | :--- | :--- | :--- |
@@ -8711,14 +8669,12 @@ Reactive Client Hook that returns `true` whenever a page navigation, history tra
8711
8669
 
8712
8670
  ##### Non-Blocking Concurrent Transitions
8713
8671
 
8714
- <a id="usenavigationloading-architecture"></a>
8715
8672
 
8716
8673
  - **Responsive UI:** Navigations execute within React's concurrent `startTransition`. The current screen remains interactive and scrollable while the server computes the destination page.
8717
8674
  - **Atomic Screen Replacement:** The existing view is preserved until the server has streamed enough of the new route to render its initial shell. `useNavigationLoading()` flips back to `false` precisely when the new DOM is painted, eliminating blank flashes.
8718
8675
 
8719
8676
  ##### Production Indicators
8720
8677
 
8721
- <a id="usenavigationloading-examples"></a>
8722
8678
 
8723
8679
  ```tsx
8724
8680
  // src/components/top-progress-bar.tsx (Client Component)
@@ -8748,15 +8704,13 @@ export function TopProgressBar() {
8748
8704
 
8749
8705
  ### 3. Type-Safe Routing (`dinou`)
8750
8706
 
8751
- <a id="type-safe-routing"></a>
8752
8707
 
8753
8708
  Dinou v7 introduces zero-runtime type safety with auto-generated declaration files and seamless IDE autocompletion for routes and parameters.
8754
8709
 
8755
8710
  ---
8756
8711
 
8757
- <a id="pageprops"></a>
8758
8712
 
8759
- #### `PageProps<T>`
8713
+ #### `PageProps`
8760
8714
 
8761
8715
  Official TypeScript interface for typing React Page components (`page.tsx`). Takes the route pattern string (constrained by `DinouRoutePattern`) as a generic parameter and automatically infers the strongly typed `params` object.
8762
8716
 
@@ -8778,9 +8732,8 @@ export function DocsPage({ params }: PageProps<"/docs/[...slug]">) {
8778
8732
 
8779
8733
  ---
8780
8734
 
8781
- <a id="layoutprops"></a>
8782
8735
 
8783
- #### `LayoutProps<T>`
8736
+ #### `LayoutProps`
8784
8737
 
8785
8738
  Official TypeScript interface for typing React Layout components (`layout.tsx`). In addition to inferred `params`, it strictly types `children: React.ReactNode`.
8786
8739
 
@@ -8799,9 +8752,8 @@ export default function BlogLayout({ children, params }: LayoutProps<"/blog/[slu
8799
8752
 
8800
8753
  ---
8801
8754
 
8802
- <a id="errorprops"></a>
8803
8755
 
8804
- #### `ErrorProps<T>`
8756
+ #### `ErrorProps`
8805
8757
 
8806
8758
  Official TypeScript interface for typing React Error Page components (`error.tsx`). In addition to inferred `params`, it strictly types the caught `error: Error`.
8807
8759
 
@@ -8822,7 +8774,6 @@ export default function DashboardError({ error, params }: ErrorProps<"/dashboard
8822
8774
 
8823
8775
  #### PageFunctions & LayoutFunctions
8824
8776
 
8825
- <a id="pagefunctions"></a>
8826
8777
 
8827
8778
  Canonical TypeScript interfaces for typing server lifecycle files (`page_functions.ts` and `layout_functions.ts`). Exported from `dinou` and re-exported from `dinou/server` for developer convenience. Both interfaces accept either a route pattern string directly (e.g. `"/blog/[slug]"`) or a direct parameters dictionary, providing complete compile-time type safety, IDE autocompletion, and index-access typing (e.g. `PageFunctions["revalidate"]`) without boilerplate.
8828
8779
 
@@ -8844,9 +8795,8 @@ export const revalidate: LayoutFunctions["revalidate"] = 3600;
8844
8795
 
8845
8796
  ---
8846
8797
 
8847
- <a id="routeparams"></a>
8848
8798
 
8849
- #### `RouteParams<T>`
8799
+ #### `RouteParams`
8850
8800
 
8851
8801
  A standalone utility type representing the inferred parameters dictionary of a given route pattern. While `PageProps` and `PageFunctions` resolve route strings directly, `RouteParams` is ideal for typing Server Actions, services, or custom helper functions that do not inherit framework props automatically.
8852
8802
 
@@ -8875,7 +8825,6 @@ export async function getDocsContent(params: RouteParams<"/docs/[...slug]">) {
8875
8825
 
8876
8826
  #### DinouRoute
8877
8827
 
8878
- <a id="dinouroute"></a>
8879
8828
 
8880
8829
  A union type representing all valid destinations in the application. It powers `<Link href>` and `router.push(href)`, automatically validating internal application routes, queries (`?key=val`), hashes (`#section`), relative paths (`./`, `../`), and external URLs (`https://...`).
8881
8830
 
@@ -8909,7 +8858,6 @@ export function ActionPanel() {
8909
8858
 
8910
8859
  #### DinouRoutePattern
8911
8860
 
8912
- <a id="dinouroutepattern"></a>
8913
8861
 
8914
8862
  A union type representing all registered filesystem folder patterns across your application (e.g. `"/blog/[slug]"`, `"/docs/[...slug]"`). It is used as the generic constraint for `PageProps<T>` and `LayoutProps<T>`, enabling instant IDE autocomplete via `Ctrl + Space` and guaranteeing compliance with TypeScript declaration emit rules (TS4058).
8915
8863
 
@@ -8935,7 +8883,6 @@ export const postMeta = definePageMeta("/blog/[slug]", ({ params }) => {
8935
8883
 
8936
8884
  ### 4. Server Context & Config (`dinou`)
8937
8885
 
8938
- <a id="server-context-config"></a>
8939
8886
 
8940
8887
  Universal Web Standards context management and root configuration primitives exported directly from `dinou`.
8941
8888
 
@@ -8943,14 +8890,11 @@ Universal Web Standards context management and root configuration primitives exp
8943
8890
 
8944
8891
  #### getContext()
8945
8892
 
8946
- <a id="getContext"></a>
8947
- <a id="getcontext"></a>
8948
8893
 
8949
8894
  Synchronously accesses the active HTTP request and response context store from anywhere within a Server Component, Server Function (`"use server"`), or route lifecycle contract (`page_functions.ts`). Powered by Node.js `AsyncLocalStorage`.
8950
8895
 
8951
8896
  ##### Request & Response Store
8952
8897
 
8953
- <a id="getcontext-store"></a>
8954
8898
 
8955
8899
  The returned `RequestContextStore` provides:
8956
8900
 
@@ -8975,7 +8919,6 @@ The returned `RequestContextStore` provides:
8975
8919
 
8976
8920
  ##### Production Patterns
8977
8921
 
8978
- <a id="getcontext-examples"></a>
8979
8922
 
8980
8923
  ```tsx
8981
8924
  // src/app/profile/page.tsx (Server Component)
@@ -9051,13 +8994,11 @@ export default async function DashboardPage() {
9051
8994
 
9052
8995
  #### defineConfig()
9053
8996
 
9054
- <a id="defineconfig"></a>
9055
8997
 
9056
8998
  Type-safe configuration helper providing autocomplete, IntelliSense, and schema validation for your application's root configuration file (`dinou.config.mjs`, `dinou.config.js`, or `dinou.config.ts`).
9057
8999
 
9058
9000
  ##### Configuration Schema
9059
9001
 
9060
- <a id="defineconfig-schema"></a>
9061
9002
 
9062
9003
  | Option | Type | Default | Description |
9063
9004
  | :--- | :--- | :--- | :--- |
@@ -9068,7 +9009,6 @@ Type-safe configuration helper providing autocomplete, IntelliSense, and schema
9068
9009
 
9069
9010
  ##### Production Configuration
9070
9011
 
9071
- <a id="defineconfig-examples"></a>
9072
9012
 
9073
9013
  ```javascript
9074
9014
  // dinou.config.mjs (Production ESM)
@@ -9109,7 +9049,6 @@ export default defineConfig({
9109
9049
 
9110
9050
  #### DinouPlugin
9111
9051
 
9112
- <a id="dinouplugin"></a>
9113
9052
 
9114
9053
  TypeScript interface defining middleware plugins for Dinou. Plugins hook into the server request lifecycle using native Web Standards (`Request` and `Response`).
9115
9054
 
@@ -9120,14 +9059,12 @@ TypeScript interface defining middleware plugins for Dinou. Plugins hook into th
9120
9059
 
9121
9060
  ##### Lifecycle & Early Exit
9122
9061
 
9123
- <a id="dinouplugin-lifecycle"></a>
9124
9062
 
9125
9063
  - **Early Exit (`Response` Returned):** If `onRequest` returns a `Response` instance (e.g. `Response.redirect()`, `Response.json()`), Dinou terminates the request immediately (<1ms). It completely bypasses React rendering, routing, and database lookups. Ideal for authentication walls, health checks, and bot blocking.
9126
9064
  - **Pass-Through & Context Enrichment (`void`):** If `onRequest` returns nothing (or `undefined`), execution proceeds to the React rendering pipeline. Any custom properties attached to `context` (e.g. `context.user = session`) are preserved in `AsyncLocalStorage` and accessible synchronously in Server Components via `getContext()`.
9127
9065
 
9128
9066
  ##### Production Plugins
9129
9067
 
9130
- <a id="dinouplugin-examples"></a>
9131
9068
 
9132
9069
  ```typescript
9133
9070
  // src/plugins/auth-guard.ts (Early Exit Pattern)
@@ -9181,8 +9118,6 @@ export const geoPlugin: DinouPlugin = {
9181
9118
 
9182
9119
  ### 5. Server Cache & Revalidation (`dinou/server`)
9183
9120
 
9184
- <a id="server-cache-revalidation"></a>
9185
- <a id="server-primitives-storage"></a>
9186
9121
 
9187
9122
  Server-side cache management, on-demand invalidation, and Micro-ISR components exported from `dinou/server`.
9188
9123
 
@@ -9190,7 +9125,6 @@ Server-side cache management, on-demand invalidation, and Micro-ISR components e
9190
9125
 
9191
9126
  #### revalidatePage()
9192
9127
 
9193
- <a id="revalidatepage"></a>
9194
9128
 
9195
9129
  Surgically evicts and regenerates the cached artifacts (`index.html` and `page.rsc`) of a single specific route. It leaves shared layout caches (`layout.rsc`), parent routes, and child subroutes completely untouched.
9196
9130
 
@@ -9223,7 +9157,6 @@ export async function updateArticle(slug: string, content: string) {
9223
9157
 
9224
9158
  #### revalidatePath()
9225
9159
 
9226
- <a id="revalidatepath"></a>
9227
9160
 
9228
9161
  Asynchronously invalidates and regenerates the targeted page **and its segment layout** (`layout.rsc`). When invoked with `{ cascade: true }` on a route that defines a layout, it recursively invalidates all child subroutes beneath that route segment.
9229
9162
 
@@ -9261,7 +9194,6 @@ export async function publishDocSection(sectionId: string) {
9261
9194
 
9262
9195
  #### revalidateTag()
9263
9196
 
9264
- <a id="revalidatetag"></a>
9265
9197
 
9266
9198
  Cross-cutting cache invalidation primitive that purges cached artifacts across disparate routes, layouts, or `<DinouCacheSlot>` components sharing the specified cache tag.
9267
9199
 
@@ -9310,7 +9242,6 @@ export async function restockProduct(productId: string, quantity: number) {
9310
9242
 
9311
9243
  ---
9312
9244
 
9313
- <a id="dinoucacheslot"></a>
9314
9245
 
9315
9246
  #### `<DinouCacheSlot>`
9316
9247
 
@@ -9318,7 +9249,6 @@ A server-side component primitive enabling independent, localized Micro-ISR cach
9318
9249
 
9319
9250
  ##### Props & Micro-ISR
9320
9251
 
9321
- <a id="dinoucacheslot-props"></a>
9322
9252
 
9323
9253
  | Prop | Type | Default | Description |
9324
9254
  | :--- | :--- | :--- | :--- |
@@ -9334,7 +9264,6 @@ A server-side component primitive enabling independent, localized Micro-ISR cach
9334
9264
 
9335
9265
  ##### Production Slot Patterns
9336
9266
 
9337
- <a id="dinoucacheslot-examples"></a>
9338
9267
 
9339
9268
  ```tsx
9340
9269
  // src/components/crypto-ticker-slot.tsx (Server Component)
@@ -9398,7 +9327,6 @@ async function CartCounter({ userId }: { userId: string }) {
9398
9327
 
9399
9328
  ### 6. Storage Adapters (`dinou/server`)
9400
9329
 
9401
- <a id="storage-adapters"></a>
9402
9330
 
9403
9331
  Storage abstractions and persistence engines exported from `dinou/server`.
9404
9332
 
@@ -9412,7 +9340,6 @@ Dinou completely decouples ISR and Micro-ISR caching logic from physical storage
9412
9340
 
9413
9341
  #### Built-In Adapters
9414
9342
 
9415
- <a id="storage-adapters-list"></a>
9416
9343
 
9417
9344
  | Adapter Class | Constructor Signature | Mechanism & Serialization | Recommended Environments |
9418
9345
  | :--- | :--- | :--- | :--- |
@@ -9429,7 +9356,6 @@ Dinou completely decouples ISR and Micro-ISR caching logic from physical storage
9429
9356
 
9430
9357
  #### StorageAdapter Interface
9431
9358
 
9432
- <a id="storage-adapters-interface"></a>
9433
9359
 
9434
9360
  Abstract base class defining the contract for all storage engines in Dinou.
9435
9361
 
@@ -9445,7 +9371,6 @@ Abstract base class defining the contract for all storage engines in Dinou.
9445
9371
 
9446
9372
  #### Custom Storage Engine
9447
9373
 
9448
- <a id="storage-adapters-custom"></a>
9449
9374
 
9450
9375
  Configure distributed caching with built-in adapters like `RedisStorage` or extend `StorageAdapter` to implement a custom database or object storage backend.
9451
9376
 
@@ -9532,8 +9457,6 @@ export class SQLiteStorage extends StorageAdapter {
9532
9457
 
9533
9458
  ### 7. Route Lifecycles & Config
9534
9459
 
9535
- <a id="route-segment-contracts"></a>
9536
- <a id="route-lifecycles-config"></a>
9537
9460
 
9538
9461
  Dinou strictly decouples UI components from server-side lifecycle contracts. Route lifecycles are declared in parallel `page_functions.ts` (or `layout_functions.ts`) files.
9539
9462
 
@@ -9541,13 +9464,11 @@ Dinou strictly decouples UI components from server-side lifecycle contracts. Rou
9541
9464
 
9542
9465
  #### getProps()
9543
9466
 
9544
- <a id="getprops"></a>
9545
9467
 
9546
9468
  The primary server-side data loader for route segments. Executed exclusively on the server before JSX component rendering begins. Data returned from `getProps()` is passed directly into the corresponding `page.tsx` or `layout.tsx` component as props.
9547
9469
 
9548
9470
  ##### Parameters & Execution
9549
9471
 
9550
- <a id="getprops-params"></a>
9551
9472
 
9552
9473
  | Parameter | Type | Description |
9553
9474
  | :--- | :--- | :--- |
@@ -9588,7 +9509,6 @@ export default function ProductPage({ product }: ProductPageProps) {
9588
9509
 
9589
9510
  #### revalidate
9590
9511
 
9591
- <a id="revalidate-config"></a>
9592
9512
 
9593
9513
  Route-level cache lifetime configuration constant in `page_functions.ts` or `layout_functions.ts`. Dictates the Incremental Static Regeneration (ISR) strategy for the segment.
9594
9514
 
@@ -9610,7 +9530,6 @@ export const revalidate: PageFunctions["revalidate"] = 3600;
9610
9530
 
9611
9531
  #### ppr
9612
9532
 
9613
- <a id="ppr-config"></a>
9614
9533
 
9615
9534
  Route-level Partial Prerendering (PPR) configuration toggle in `page_functions.ts` or `layout_functions.ts`. Enables or disables hybrid static-shell delivery with streaming dynamic Suspense holes for this route segment, overriding the global `ppr` setting in `dinou.config.mjs`.
9616
9535
 
@@ -9632,7 +9551,6 @@ export const ppr: LayoutFunctions["ppr"] = true;
9632
9551
 
9633
9552
  #### getCacheTags
9634
9553
 
9635
- <a id="getcachetags"></a>
9636
9554
 
9637
9555
  Route-level cache tagging contract in `page_functions.ts` or `layout_functions.ts`. Associates semantic cache tags with the generated page or layout artifacts, enabling surgical cross-cutting invalidation via `revalidateTag(tag)`.
9638
9556
 
@@ -9653,7 +9571,6 @@ export const getCacheTags: PageFunctions<"/products/[id]">["getCacheTags"] = (pa
9653
9571
 
9654
9572
  #### getStaticPaths
9655
9573
 
9656
- <a id="getstaticpaths"></a>
9657
9574
 
9658
9575
  Build-time static path pre-generation contract for dynamic routes (`[slug]`, `[...slug]`). Defines the set of parameter combinations pre-rendered to static HTML during `dinou build`.
9659
9576
 
@@ -9680,7 +9597,6 @@ export const getStaticPaths: PageFunctions<"/blog/[slug]">["getStaticPaths"] = a
9680
9597
 
9681
9598
  #### allowISG
9682
9599
 
9683
- <a id="allowisg"></a>
9684
9600
 
9685
9601
  Defines the fallback policy for dynamic routes when a requested path was **not** pre-generated at build time by `getStaticPaths`.
9686
9602
 
@@ -9701,7 +9617,6 @@ export const allowISG: PageFunctions["allowISG"] = false;
9701
9617
 
9702
9618
  #### validateParams()
9703
9619
 
9704
- <a id="validateparams"></a>
9705
9620
 
9706
9621
  Route perimeter guard that evaluates incoming dynamic route parameters before pipeline execution. Returning `false` immediately terminates the request with a clean 404 Not Found HTTP response without invoking `getProps` or evaluating downstream components.
9707
9622
 
@@ -9742,8 +9657,7 @@ export const validateParams: LayoutFunctions<"/[organization]">["validateParams"
9742
9657
 
9743
9658
  ---
9744
9659
 
9745
- <a id="cheatsheet"></a>
9746
- ## ⚡ Dinou Complete Cheatsheet
9660
+ ## Dinou Complete Cheatsheet
9747
9661
 
9748
9662
  `Executive Reference` · `Dinou v7`
9749
9663
 
@@ -9755,14 +9669,12 @@ At-a-glance high-density desktop reference for file conventions, dynamic route s
9755
9669
 
9756
9670
  ---
9757
9671
 
9758
- <a id="file-conventions"></a>
9759
9672
  ### 1. File Conventions Cheatsheet
9760
9673
 
9761
9674
  `Filesystem`
9762
9675
 
9763
9676
  Directories inside `src/app/` directly map to URL paths. Standardized file names define UI leaves, layout shells, and decoupled server contracts.
9764
9677
 
9765
- <a id="route-components"></a>
9766
9678
  #### Route Components & Lifecycles
9767
9679
 
9768
9680
  | Filename | Role | Scope | Key Responsibility |
@@ -9777,7 +9689,6 @@ Directories inside `src/app/` directly map to URL paths. Standardized file names
9777
9689
  > [!NOTE]
9778
9690
  > **Hierarchical Bubble-Up:** Dinou bubbles unhandled errors and 404s upward to the closest ancestor handler. A nested `src/app/blog/[slug]/not_found.tsx` intercepts 404s before the root `src/app/not_found.tsx`.
9779
9691
 
9780
- <a id="layout-flags"></a>
9781
9692
  #### Layout Control Flags (Empty Files)
9782
9693
 
9783
9694
  Create these **empty files** (zero bytes, no extension) inside a route directory to modify layout inheritance without writing custom wrapper logic:
@@ -9789,7 +9700,6 @@ Create these **empty files** (zero bytes, no extension) inside a route directory
9789
9700
  | `no_layout_error` | `error.tsx` | Renders the segment's 500 error page without any surrounding layout shells. |
9790
9701
  | `no_layout_not_found` | `not_found.tsx` | Renders the segment's 404 not found page without any surrounding layout shells. |
9791
9702
 
9792
- <a id="route-escaping"></a>
9793
9703
  #### Route Escaping (`_prefix`)
9794
9704
 
9795
9705
  Any directory prefixed with an underscore (`_folder`) is completely ignored by the route compiler.
@@ -9800,14 +9710,12 @@ Any directory prefixed with an underscore (`_folder`) is completely ignored by t
9800
9710
 
9801
9711
  ---
9802
9712
 
9803
- <a id="route-syntax"></a>
9804
9713
  ### 2. Route Syntax & Types
9805
9714
 
9806
9715
  `Type Safety`
9807
9716
 
9808
9717
  Dinou provides zero-runtime type safety by inferring route parameter types directly from folder bracket naming conventions.
9809
9718
 
9810
- <a id="route-patterns"></a>
9811
9719
  #### Route Patterns & Inferred Params
9812
9720
 
9813
9721
  | Folder Pattern | Example URL | Inferred `params` Type | Behavior |
@@ -9819,7 +9727,6 @@ Dinou provides zero-runtime type safety by inferring route parameter types direc
9819
9727
  | `/dash/[[tab]]` | `/dash`, `/dash/billing` | `{ tab?: string }` | Optional single parameter. |
9820
9728
  | `/(auth)/login` | `/login` | `{}` | Route group. Organizes files without adding a URL segment. |
9821
9729
 
9822
- <a id="type-helpers"></a>
9823
9730
  #### Type-Safe Routing Helpers (`dinou`)
9824
9731
 
9825
9732
  | Helper Type | TypeScript Signature | Purpose | API Ref |
@@ -9833,27 +9740,24 @@ Dinou provides zero-runtime type safety by inferring route parameter types direc
9833
9740
 
9834
9741
  ---
9835
9742
 
9836
- <a id="server-contracts"></a>
9837
9743
  ### 3. Server Lifecycle Contracts
9838
9744
 
9839
9745
  `Server Only`
9840
9746
 
9841
9747
  Contracts declared in `page_functions.ts` (or `layout_functions.ts`). Executed exclusively on the server, completely decoupled from React render passes.
9842
9748
 
9843
- <a id="lifecycle-contracts"></a>
9844
9749
  #### Exported Contracts Table
9845
9750
 
9846
9751
  | Exported Contract | Signature | Default | Execution & Purpose | API Ref |
9847
9752
  | :--- | :--- | :--- | :--- | :---: |
9848
9753
  | `getProps(params)` | `(params) => Promise<T> | T` | `{}` | Server data loader. Return value is directly passed as props to `page.tsx` or `layout.tsx`. | [Docs](#getprops) |
9849
- | `revalidate` | `number | false | (() => ...)` | `false` (SSG) | Cache TTL in seconds. `0` = SSR (dynamic), `>= 1` = ISR, `false` = Static SSG. | [Docs](#revalidate-config) |
9850
- | `ppr` | `boolean | (() => boolean | Promise<boolean>)` | `false` | Enables Partial Prerendering: static shell built at build time, dynamic holes stream via React Suspense. | [Docs](#ppr-config) |
9754
+ | `revalidate` | `number | false | (() => ...)` | `false` (SSG) | Cache TTL in seconds. `0` = SSR (dynamic), `>= 1` = ISR, `false` = Static SSG. | [Docs](#revalidate) |
9755
+ | `ppr` | `boolean | (() => boolean | Promise<boolean>)` | `false` | Enables Partial Prerendering: static shell built at build time, dynamic holes stream via React Suspense. | [Docs](#ppr) |
9851
9756
  | `getCacheTags(params)` | `(params) => string[] | Promise<string[]>` | `[]` | Associates cache tags with the route for targeted on-demand invalidation via `revalidateTag(tag)`. | [Docs](#getcachetags) |
9852
9757
  | `getStaticPaths()` | `() => StaticPathItem[] | Promise<...>` | `[]` | Pre-generates dynamic parameter combinations during build time for SSG rendering. | [Docs](#getstaticpaths) |
9853
9758
  | `allowISG` | `boolean | (() => boolean | Promise<boolean>)` | `true` | When `true`, ungenerated paths render on-demand on first visit. When `false`, ungenerated paths return 404. | [Docs](#allowisg) |
9854
9759
  | `validateParams(params)` | `(params) => boolean | Promise<boolean>` | `() => true` | Route parameter gatekeeper. Returning `false` immediately terminates with a 404 before calling `getProps`. | [Docs](#validateparams) |
9855
9760
 
9856
- <a id="revalidate-modes"></a>
9857
9761
  #### Revalidation Modes (SSR vs ISR vs SSG)
9858
9762
 
9859
9763
  | Export Value | Rendering Mode | Cache Behavior | Ideal Use Case |
@@ -9864,14 +9768,12 @@ Contracts declared in `page_functions.ts` (or `layout_functions.ts`). Executed e
9864
9768
 
9865
9769
  ---
9866
9770
 
9867
- <a id="navigation-hooks"></a>
9868
9771
  ### 4. Client Navigation & Hooks
9869
9772
 
9870
9773
  `dinou`
9871
9774
 
9872
9775
  Declarative navigation components and reactive client hooks for routing state and micro-ISR slot manipulation.
9873
9776
 
9874
- <a id="client-primitives"></a>
9875
9777
  #### Link & Redirection Primitives
9876
9778
 
9877
9779
  | Export | Scope | Signature / Props | Behavior | API Ref |
@@ -9880,7 +9782,6 @@ Declarative navigation components and reactive client hooks for routing state an
9880
9782
  | `<ClientRedirect>` | `Client` | `to: string, replace?: boolean` | Declarative redirect rendered inside component tree during render phase. | [Docs](#clientredirect) |
9881
9783
  | `redirect()` | `Universal` | `(path: string, status?: number) => never` | HTTP 307 on server (pre-header flush) or SPA client replace if streaming/client. | [Docs](#redirect) |
9882
9784
 
9883
- <a id="location-hooks"></a>
9884
9785
  #### Router & Navigation Hooks
9885
9786
 
9886
9787
  | Hook / Helper | Scope | Returned Interface | Common Use Case | API Ref |
@@ -9893,14 +9794,12 @@ Declarative navigation components and reactive client hooks for routing state an
9893
9794
 
9894
9795
  ---
9895
9796
 
9896
- <a id="server-primitives"></a>
9897
9797
  ### 5. Server Primitives & Cache
9898
9798
 
9899
9799
  `dinou & dinou/server`
9900
9800
 
9901
9801
  Server-side context providers, micro-ISR slot primitives, and cluster cache purge APIs.
9902
9802
 
9903
- <a id="context-and-slots"></a>
9904
9803
  #### getContext & DinouCacheSlot
9905
9804
 
9906
9805
  | Export | Package | Signature | Purpose & Mechanics | API Ref |
@@ -9908,9 +9807,8 @@ Server-side context providers, micro-ISR slot primitives, and cluster cache purg
9908
9807
  | `getContext()` | `dinou` | `() => ServerContext | null` | Synchronous HTTP access via AsyncLocalStorage: `req.cookies`, `req.headers`, `res.cookie()`, `res.setHeader()`. | [Docs](#getcontext) |
9909
9808
  | `<DinouCacheSlot>` | `dinou/server` | `id, revalidate?, tag?, tags?` | Micro-ISR server component. Caches an independent sub-tree without re-evaluating parent layouts or siblings. | [Docs](#dinoucacheslot) |
9910
9809
  | `defineConfig(config)` | `dinou` | `(config: DinouConfig) => DinouConfig` | Type helper for `dinou.config.mjs` (reactStrictMode, ppr, storage, plugins). | [Docs](#defineconfig) |
9911
- | `Storage Adapters` | `dinou/server` | `MemoryStorage, RedisStorage` | ISR storage engines for single server or distributed multi-instance clusters. | [Docs](#storage-adapters-list) |
9810
+ | `Storage Adapters` | `dinou/server` | `MemoryStorage, RedisStorage` | ISR storage engines for single server or distributed multi-instance clusters. | [Docs](#built-in-adapters) |
9912
9811
 
9913
- <a id="cache-invalidation"></a>
9914
9812
  #### On-Demand Cache Invalidation (`dinou/server`)
9915
9813
 
9916
9814
  | Function | Target | Signature | Purge Effect | API Ref |
@@ -9921,14 +9819,12 @@ Server-side context providers, micro-ISR slot primitives, and cluster cache purg
9921
9819
 
9922
9820
  ---
9923
9821
 
9924
- <a id="decision-matrix"></a>
9925
9822
  ### 6. Decision Matrix: When to Use What
9926
9823
 
9927
9824
  `Architectural Guide`
9928
9825
 
9929
9826
  Quick comparative decision tables to help you pick the right primitive for caching, navigation, and state access without trial and error.
9930
9827
 
9931
- <a id="matrix-cache"></a>
9932
9828
  #### Cache Invalidation: Which method should you call?
9933
9829
 
9934
9830
  | Method | Caller Environment | Scope of Impact | When to Choose It |
@@ -9938,7 +9834,6 @@ Quick comparative decision tables to help you pick the right primitive for cachi
9938
9834
  | `refreshSlot(slotId)` | Client Component (Browser) | Single targeted slot on current page | **Zero layout re-render:** when an interactive client widget updates (e.g. cart badge counter or mini ticker) without touching the rest of the page. |
9939
9835
  | `router.refresh()` | Client Component (Browser) | Entire active page | When a client action needs fresh server props for the whole page without losing client state or scrolling to top. |
9940
9836
 
9941
- <a id="matrix-redirects"></a>
9942
9837
  #### Redirection: Which redirection strategy should you use?
9943
9838
 
9944
9839
  | Strategy | Context / Location | HTTP / Browser Mechanism | When to Choose It |
@@ -9948,7 +9843,6 @@ Quick comparative decision tables to help you pick the right primitive for cachi
9948
9843
  | `<ClientRedirect to="..." />` | Client Component (JSX render) | Client-side router push/replace | Declarative fallback rendering in client tabs, wizard step redirections, or empty states. |
9949
9844
  | `router.replace(url)` | Client Event Handler | History replace without entry | Post-submission redirect where clicking browser "Back" should not re-submit the action (e.g. login form, payment checkout). |
9950
9845
 
9951
- <a id="matrix-params"></a>
9952
9846
  #### Route Parameter Access: Where should you read route data?
9953
9847
 
9954
9848
  | Access Pattern | Environment | Return Type | When to Choose It |
@@ -9964,14 +9858,10 @@ Quick comparative decision tables to help you pick the right primitive for cachi
9964
9858
 
9965
9859
  ---
9966
9860
 
9967
- <a id="changelog"></a>
9968
- <a id="-changelog"></a>
9969
- ## 📜 Changelog
9861
+ ## Changelog
9970
9862
 
9971
9863
  For a detailed list of changes, enhancements, and bug fixes across versions, see the [CHANGELOG.md](./CHANGELOG.md).
9972
9864
 
9973
- <a id="license"></a>
9974
- <a id="-license"></a>
9975
- ## 📄 License
9865
+ ## License
9976
9866
 
9977
9867
  Dinou is licensed under the [MIT License](./LICENSE.md).