dinou 9.3.0 → 10.0.1

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.
Files changed (166) hide show
  1. package/CHANGELOG.md +196 -0
  2. package/README.md +157 -132
  3. package/dinou/adapters/bun.js +34 -5
  4. package/dinou/adapters/cloudflare.js +110 -17
  5. package/dinou/adapters/deno.js +46 -8
  6. package/dinou/adapters/netlify.js +86 -50
  7. package/dinou/adapters/node.js +8 -0
  8. package/dinou/assets.d.ts +32 -5
  9. package/dinou/bun/build.js +190 -106
  10. package/dinou/cli.js +992 -532
  11. package/dinou/cloudflare/build.js +187 -106
  12. package/dinou/compiled/autoprefixer/index.js +509 -517
  13. package/dinou/compiled/babel-core/index.js +738 -716
  14. package/dinou/compiled/babel-generator/index.js +341 -299
  15. package/dinou/compiled/babel-loader/index.js +766 -744
  16. package/dinou/compiled/babel-parser/index.js +2 -2
  17. package/dinou/compiled/babel-plugin-react-compiler/index.js +178 -178
  18. package/dinou/compiled/babel-plugin-syntax-import-meta/index.js +4 -4
  19. package/dinou/compiled/babel-preset-react/index.js +752 -730
  20. package/dinou/compiled/babel-preset-typescript/index.js +738 -716
  21. package/dinou/compiled/babel-traverse/index.js +463 -433
  22. package/dinou/compiled/babel-types/index.js +176 -176
  23. package/dinou/compiled/chokidar/index.js +4 -4
  24. package/dinou/compiled/commander/index.js +15 -15
  25. package/dinou/compiled/copy-webpack-plugin/index.js +433 -425
  26. package/dinou/compiled/css-loader/index.js +289 -289
  27. package/dinou/compiled/css-loader/runtime/api.js +85 -0
  28. package/dinou/compiled/css-loader/runtime/getUrl.js +26 -0
  29. package/dinou/compiled/css-loader/runtime/noSourceMaps.js +5 -0
  30. package/dinou/compiled/css-loader/runtime/package.json +3 -0
  31. package/dinou/compiled/css-loader/runtime/sourceMaps.js +16 -0
  32. package/dinou/compiled/fast-glob/index.js +5810 -0
  33. package/dinou/compiled/generic-names/index.js +16 -16
  34. package/dinou/compiled/mini-css-extract-plugin/{chunk-YYEJWYXE.js → chunk-R6DP5ZYM.js} +36 -36
  35. package/dinou/compiled/mini-css-extract-plugin/hmr/hotModuleReplacement.js +253 -0
  36. package/dinou/compiled/mini-css-extract-plugin/hmr/normalize-url.js +39 -0
  37. package/dinou/compiled/mini-css-extract-plugin/hmr/package.json +3 -0
  38. package/dinou/compiled/mini-css-extract-plugin/index.js +1 -1
  39. package/dinou/compiled/mini-css-extract-plugin/loader.js +5 -5
  40. package/dinou/compiled/postcss/index.js +83 -83
  41. package/dinou/compiled/postcss-import/index.js +147 -117
  42. package/dinou/compiled/postcss-modules/index.js +216 -216
  43. package/dinou/compiled/resolve/index.js +1224 -0
  44. package/dinou/compiled/rollup-plugin-babel/index.js +753 -731
  45. package/dinou/compiled/rollup-plugin-commonjs/index.js +43 -38
  46. package/dinou/compiled/rollup-plugin-delete/index.js +615 -253
  47. package/dinou/compiled/rollup-plugin-json/index.js +22 -18
  48. package/dinou/compiled/rollup-plugin-node-resolve/index.js +130 -100
  49. package/dinou/compiled/rollup-plugin-postcss/index.js +3299 -3277
  50. package/dinou/compiled/rollup-plugin-replace/index.js +34 -29
  51. package/dinou/compiled/tailwindcss-postcss/index.js +214 -211
  52. package/dinou/compiled/vendors-manifest.json +59 -83
  53. package/dinou/core/asset-extensions.js +482 -33
  54. package/dinou/core/bailout-proxy.js +21 -2
  55. package/dinou/core/build-static-pages.js +523 -371
  56. package/dinou/core/builtin-asset-extensions.js +63 -0
  57. package/dinou/core/cache-revalidate.js +449 -256
  58. package/dinou/core/cache-slot.js +289 -79
  59. package/dinou/core/client-webpack.jsx +470 -39
  60. package/dinou/core/client.jsx +402 -39
  61. package/dinou/core/config.js +3 -0
  62. package/dinou/core/copy-static-dirs.js +98 -0
  63. package/dinou/core/createScopedName.js +22 -4
  64. package/dinou/core/dinou-paths.js +1 -1
  65. package/dinou/core/discover-layouts.js +200 -0
  66. package/dinou/core/edge-ssr.js +1 -1
  67. package/dinou/core/ensure-vendor-mode.js +78 -19
  68. package/dinou/core/env.js +544 -0
  69. package/dinou/core/export-static.js +41 -9
  70. package/dinou/core/generate-route-types.js +989 -95
  71. package/dinou/core/generate-static-rsc.js +5 -6
  72. package/dinou/core/generate-static.js +45 -6
  73. package/dinou/core/get-abs-path-with-ext.js +217 -75
  74. package/dinou/core/get-asset-from-manifest.js +19 -8
  75. package/dinou/core/get-error-jsx.js +4 -5
  76. package/dinou/core/get-file-path-and-dynamic-params.js +561 -338
  77. package/dinou/core/get-jsx.js +220 -53
  78. package/dinou/core/handler.js +1647 -466
  79. package/dinou/core/import-module.js +7 -0
  80. package/dinou/core/layout-functions.js +72 -13
  81. package/dinou/core/link.jsx +34 -6
  82. package/dinou/core/load-dinou-config.js +520 -89
  83. package/dinou/core/manifest-provider.js +4 -14
  84. package/dinou/core/navigation-utils.js +141 -3
  85. package/dinou/core/navigation.js +134 -50
  86. package/dinou/core/node-middleware-runner.js +165 -0
  87. package/dinou/core/postcss-pipeline.js +236 -0
  88. package/dinou/core/ppr-context.js +114 -22
  89. package/dinou/core/ppr-runtime.js +391 -127
  90. package/dinou/core/redirect.jsx +1 -1
  91. package/dinou/core/render-jsx-to-client-jsx.js +216 -48
  92. package/dinou/core/request-context.js +59 -3
  93. package/dinou/core/resolve-contextual-dinou.js +523 -0
  94. package/dinou/core/resolve-setup-files.js +85 -27
  95. package/dinou/core/revalidating.js +10 -2
  96. package/dinou/core/route-generator.js +6 -2
  97. package/dinou/core/rsc-renderer.js +4 -1
  98. package/dinou/core/run-ssg.js +6 -0
  99. package/dinou/core/runtime-env.js +265 -0
  100. package/dinou/core/server-css-modules-plugin.js +155 -0
  101. package/dinou/core/server-function-proxy-webpack.js +27 -2
  102. package/dinou/core/server-function-proxy.js +27 -2
  103. package/dinou/core/slot.js +47 -2
  104. package/dinou/core/static-assets.js +503 -0
  105. package/dinou/core/storage-adapter.js +452 -24
  106. package/dinou/core/transform-server-functions.js +272 -24
  107. package/dinou/core/tsconfig-aliases.js +964 -0
  108. package/dinou/core/uneject.js +640 -0
  109. package/dinou/core/url-resolver.js +1 -1
  110. package/dinou/core/vfs.js +11 -2
  111. package/dinou/css.d.ts +4 -1
  112. package/dinou/deno/build.js +205 -153
  113. package/dinou/deno/seed-kv.js +4 -0
  114. package/dinou/env.d.ts +22 -2
  115. package/dinou/esbuild/build.js +40 -50
  116. package/dinou/esbuild/dev.js +33 -7
  117. package/dinou/esbuild/helpers-esbuild/get-config-esbuild-prod.js +41 -16
  118. package/dinou/esbuild/helpers-esbuild/get-config-esbuild.js +51 -49
  119. package/dinou/esbuild/helpers-esbuild/get-esbuild-entries.js +73 -60
  120. package/dinou/esbuild/helpers-esbuild/swc-disk-cache.js +35 -16
  121. package/dinou/esbuild/helpers-esbuild/write.js +13 -3
  122. package/dinou/esbuild/plugins-esbuild/assets-plugin.js +100 -238
  123. package/dinou/esbuild/plugins-esbuild/babel-react-compiler-plugin.js +73 -29
  124. package/dinou/esbuild/plugins-esbuild/css-processor-plugin.js +283 -91
  125. package/dinou/esbuild/plugins-esbuild/manifest-generator-plugin.js +3 -5
  126. package/dinou/esbuild/plugins-esbuild/react-client-manifest-plugin.js +9 -3
  127. package/dinou/esbuild/plugins-esbuild/server-functions-plugin.js +4 -3
  128. package/dinou/esbuild/plugins-esbuild/stable-chunk-names-and-maps-plugin.js +10 -1
  129. package/dinou/esbuild/plugins-postcss/postcss-extract-plugin.js +84 -21
  130. package/dinou/esbuild/react-refresh/esm-hmr/client.js +31 -10
  131. package/dinou/esbuild/react-refresh/esm-hmr-plugin.js +48 -18
  132. package/dinou/esbuild/react-refresh/is-react-refresh-boundary.js +9 -1
  133. package/dinou/esbuild/react-refresh/react-refresh-runtime.js +13 -7
  134. package/dinou/index.d.ts +1028 -88
  135. package/dinou/node/build.js +138 -74
  136. package/dinou/node/bundle-dual-engine.js +393 -131
  137. package/dinou/node/dev.js +1005 -275
  138. package/dinou/package.json +11 -34
  139. package/dinou/rollup/postcss.config.js +3 -4
  140. package/dinou/rollup/react-refresh/esm-hmr/client.js +31 -10
  141. package/dinou/rollup/react-refresh/react-refresh-wrap-modules.js +16 -13
  142. package/dinou/rollup/react-refresh/rollup-plugin-esm-hmr.js +53 -7
  143. package/dinou/rollup/rollup-plugins/dinou-asset-plugin.js +58 -20
  144. package/dinou/rollup/rollup-plugins/manifest-generator-plugin.js +16 -7
  145. package/dinou/rollup/rollup-plugins/rollup-plugin-react-client-manifest.js +118 -42
  146. package/dinou/rollup/rollup-plugins/rollup-plugin-server-functions.js +48 -36
  147. package/dinou/rollup/rollup.config.js +174 -101
  148. package/dinou/scripts/build-vendors.js +123 -33
  149. package/dinou/server.d.ts +126 -15
  150. package/dinou/webpack/helpers/get-webpack-entries.js +87 -41
  151. package/dinou/webpack/helpers/patch-webpack-internals.js +93 -1
  152. package/dinou/webpack/loaders/server-functions-loader.js +1 -1
  153. package/dinou/webpack/plugins/manifest-generator-plugin.js +27 -7
  154. package/dinou/webpack/plugins/server-functions-plugin.js +39 -12
  155. package/dinou/webpack/plugins/webpack-memory-plugin.js +25 -12
  156. package/dinou/webpack/postcss.config.js +3 -4
  157. package/dinou/webpack/webpack.config.js +408 -132
  158. package/eject.js +6 -224
  159. package/package.json +7 -9
  160. package/dinou/compiled/cross-env/index.js +0 -661
  161. package/dinou/compiled/dotenv/index.js +0 -375
  162. package/dinou/compiled/esbuild-copy-static-files/index.js +0 -63
  163. package/dinou/compiled/esbuild-tsconfig-paths/index.js +0 -1314
  164. package/dinou/compiled/rollup-plugin-copy/index.js +0 -12066
  165. package/dinou/compiled/rollup-plugin-tsconfig-paths/index.js +0 -569
  166. package/dinou/compiled/tsconfig-paths-webpack-plugin/index.js +0 -3956
package/README.md CHANGED
@@ -1,16 +1,16 @@
1
1
  # Dinou
2
2
 
3
3
  [![Documentation](https://img.shields.io/badge/docs-dinou.dev-blue?style=flat-square)](https://dinou.dev)
4
- [![Version](https://img.shields.io/badge/version-9.3.0-orange?style=flat-square)](https://www.npmjs.com/package/dinou)
4
+ [![Version](https://img.shields.io/badge/version-10.0.1-orange?style=flat-square)](https://www.npmjs.com/package/dinou)
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](./LICENSE.md)
6
6
 
7
7
  **The Ejectable Full-Stack React 19 Framework.**
8
8
 
9
9
  Build full-stack web applications with native **React Server Components (RSC)**, progressive streaming SSR, compile-time type-safe routing, **3-Dimensional Caching** (**Horizontal Segmentation**, **Vertical `<DinouCacheSlot>` Micro-ISR**, and **Temporal Segmentation / Partial Prerendering (PPR)**), **Dual-Mode Vendoring**, and universal multi-platform deployment (**Node.js**, **Bun**, **Deno**, **Cloudflare Workers**, **Netlify**, and **Static Export**) with zero vendor lock-in.
10
10
 
11
- > 📚 **Full Documentation, Guides & Interactive Tutorials:** **[https://dinou.dev](https://dinou.dev)**
11
+ > 📚 **Full Documentation, Guides & Interactive Tutorials:** **[https://dinou.dev](https://dinou.dev)** · **LLM Docs:** [llms.txt](https://dinou.dev/llms.txt) · [llms-full.txt](https://dinou.dev/llms-full.txt)
12
12
  >
13
- > 🤖 **AI Agent Ready:** This `README.md` is intentionally engineered as a **high-density, single-pass technical specification (< 700 lines / < 38 KB)** so AI coding agents can read the entire framework architecture, public APIs, and caching invariants in a single tool call.
13
+ > 🤖 **AI Agent Ready:** This `README.md` is intentionally engineered as a **high-density, single-pass technical specification (< 700 lines / < 45 KB)** so AI coding agents can read the entire framework architecture, public APIs, and caching invariants in a single tool call.
14
14
 
15
15
  ---
16
16
 
@@ -27,9 +27,9 @@ Build full-stack web applications with native **React Server Components (RSC)**,
27
27
  - [5.4. The Triple Synergy (Horizontal + Vertical + Temporal / PPR)](#54-the-triple-synergy-horizontal--vertical--temporal--ppr)
28
28
  6. [Client Navigation, Router Cache & Hooks](#6-client-navigation-router-cache--hooks)
29
29
  7. [Server Functions (`"use server"`), Context & The Dinou Pattern](#7-server-functions-use-server-context--the-dinou-pattern)
30
- 8. [Configuration (`dinou.config.mjs`), Middleware (`onRequest`) & Storage Adapters](#8-configuration-dinouconfigmjs-middleware-onrequest--storage-adapters)
30
+ 8. [Configuration (`dinou.config.ts`), Middleware (`onRequest`) & Storage Adapters](#8-configuration-dinouconfigts-middleware-onrequest--storage-adapters)
31
31
  9. [Styling, Assets, Environment Variables & Aliases](#9-styling-assets-environment-variables--aliases)
32
- 10. [Bundlers, Deployment Targets, Dual-Mode Vendoring & Eject](#10-bundlers-deployment-targets-dual-mode-vendoring--eject)
32
+ 10. [Bundlers, Deployment Targets, Dual-Mode Vendoring & Eject / Uneject](#10-bundlers-deployment-targets-dual-mode-vendoring--eject--uneject)
33
33
  11. [Complete Public Exports Cheat-Sheet](#11-complete-public-exports-cheat-sheet)
34
34
 
35
35
  ---
@@ -49,19 +49,21 @@ npm run dev
49
49
 
50
50
  ### Core CLI Commands (`npx dinou <command>`)
51
51
 
52
- All commands accept the global **`-u` / `--unvendorized`** flag (or `DINOU_UNVENDORIZED=true`) to resolve internal toolchain dependencies from standard `node_modules` instead of Dinou's pre-bundled `dinou/compiled/` vendor bundles.
52
+ All commands accept **`-u` / `--unvendorized`** (e.g. `npm run dev -- -u`, `npx dinou dev -u`, or `DINOU_UNVENDORIZED=true`) to resolve toolchain packages from `node_modules` instead of `dinou/compiled/`.
53
53
 
54
54
  | Command | Bundler Variants (`:esbuild` default, `:rollup`, `:webpack`) | Description |
55
55
  | :--- | :--- | :--- |
56
56
  | `dinou dev` | `dev:esbuild`, `dev:rollup`, `dev:webpack` | Start development server with HMR & Fast Refresh. |
57
- | `dinou build` / `build:node` | `build:node:{esbuild,rollup,webpack}` | Build production bundle and pre-render static routes for Node.js. |
58
- | `dinou start` / `start:node` | `start:node:{esbuild,rollup,webpack}` | Start production Node.js server. |
59
- | `dinou build:cloudflare` | `build:cloudflare:{esbuild,rollup,webpack}` | Build for Cloudflare Workers (`workerd` + KV). |
57
+ | `dinou build` / `build:node` | `build:node:{esbuild,rollup,webpack}` | Build production bundle and pre-render static routes for Node.js (and Netlify). |
58
+ | `dinou start` / `start:node` | `start:node:{esbuild,rollup,webpack}` | Start production Node.js server (`.dinou/node/server.mjs`). |
59
+ | `dinou build:netlify` | `build:netlify:{esbuild,rollup,webpack}` | Build dedicated single-file AOT Netlify Functions v2 bundle (`.dinou/netlify/functions/ssr.mjs`). |
60
+ | `dinou build:cloudflare` | `build:cloudflare:{esbuild,rollup,webpack}` | Build for Cloudflare Workers (`workerd`, `.dinou/cloudflare/assets`, KV). |
60
61
  | `dinou build:bun` / `start:bun` | `build:bun:{esbuild,rollup,webpack}` | Build and start for Bun runtime (`build:bun:pure` runs 100% under Bun). |
61
62
  | `dinou build:deno` / `start:deno` | `build:deno:{esbuild,rollup,webpack}` | Build and seed Deno KV for Deno / Deno Deploy. |
62
- | `dinou build:{node,bun,deno}:compile` | `...compile:{linux,linux_arm,mac,win}:{bundler}` | Compile standalone single-file native executable (`dist/`). |
63
- | `dinou export-static` | `export-static:{esbuild,rollup,webpack}` | Export pure static site to `dist/` (HTML + RSC payloads + assets). |
64
- | `dinou eject` | — | Eject full Dinou compiler & runtime into `./dinou` at project root. |
63
+ | `dinou build:{node,bun,deno}:compile` | `...compile:{linux,linux_arm,mac,win}:{bundler}` | Compile standalone single-file native executable (`dist/server`). |
64
+ | `dinou export-static` | `export-static:{esbuild,rollup,webpack}` | Export standalone static SPA site to `out/` (`index.html`, `page.rsc`, `layout.rsc`, assets). |
65
+ | `dinou typegen` | — | Generate `.dinou/types/routes.d.ts` & `.dinou/routes/**/dinou.{js,d.ts}`. |
66
+ | `dinou eject` / `uneject` | — | Eject full Dinou compiler & runtime into `./dinou`, or transactionally revert via `npm run uneject`. |
65
67
 
66
68
  ---
67
69
 
@@ -73,8 +75,8 @@ Routes live directly inside **`src/`** (not `src/app/`). A directory becomes a r
73
75
  my-app/
74
76
  ├── public/ # Static files served at "/" (copied to .dinou/dist3)
75
77
  ├── src/
76
- │ ├── layout.tsx # Root Layout (wraps<html>, <head>, <body>)
77
- │ ├── layout_functions.ts # Root Layout server lifecycle (getProps, revalidate, getCacheTags, ppr)
78
+ │ ├── layout.tsx # Root Layout (wraps <html>, <head>, <body>)
79
+ │ ├── layout_functions.ts # Root Layout server lifecycle (getProps, getStaticPaths, allowISG, revalidate, getCacheTags, ppr)
78
80
  │ ├── page.tsx # Home route ("/")
79
81
  │ ├── page_functions.ts # Home route server lifecycle (getProps, revalidate, getCacheTags, ppr)
80
82
  │ ├── error.tsx # Root 500 error boundary page
@@ -83,9 +85,10 @@ my-app/
83
85
  │ └── [slug]/
84
86
  │ ├── page.tsx # Dynamic route ("/blog/:slug")
85
87
  │ └── page_functions.ts
86
- ├── dinou.config.mjs # Optional framework config, plugins, storage & middleware
88
+ ├── dinou.config.ts # Optional framework config, plugins, storage & middleware (.ts/.mjs/.js/.cjs)
87
89
  ├── dinou.setup.ts # Optional early setup/polyfill file injected into all environments
88
- └── tsconfig.json # TypeScript config (includes ".dinou/types/routes.d.ts")
90
+ ├── dinou-env.d.ts # Ambient asset declarations (/// <reference types="dinou/env" />)
91
+ └── tsconfig.json # TypeScript config (rootDirs: ["src", ".dinou/routes"] + ".dinou/types/**/*.d.ts")
89
92
  ```
90
93
 
91
94
  ### Special Route Files (`src/**/`)
@@ -95,7 +98,7 @@ my-app/
95
98
  | `page.{tsx,jsx,ts,js}` | Universal (`async` RSC or `"use client"`) | Primary UI for the URL segment. Receives `{ params }` plus all props returned by `getProps`. |
96
99
  | `layout.{tsx,jsx,ts,js}` | Universal (`async` RSC or `"use client"`) | Persistent wrapper around child routes. Does **not** remount on child SPA navigation. Receives `{ children, params, ...parallelSlots }` plus props from `layout_functions.ts` `getProps`. |
97
100
  | `page_functions.{ts,js}` | Server-Only | Exports `getProps`, `getStaticPaths`, `validateParams`, `allowISG`, `revalidate`, `getCacheTags`, `ppr`. |
98
- | `layout_functions.{ts,js}` | Server-Only | Exports `getProps`, `validateParams`, `revalidate`, `getCacheTags`, `ppr` for the layout segment independently of child pages. |
101
+ | `layout_functions.{ts,js}` | Server-Only | Exports `getProps`, `getStaticPaths`, `validateParams`, `allowISG`, `revalidate`, `getCacheTags`, `ppr` for the layout segment independently of child pages. |
99
102
  | `error.{tsx,jsx,ts,js}` | Universal | Renders when an unhandled error occurs in the segment or its descendants (bubbles up to closest ancestor `error.*`). Receives `{ error, params }`. |
100
103
  | `not_found.{tsx,jsx,ts,js}` | Universal | Renders on unmatched URLs or when `validateParams` returns `false` / `allowISG = false` (bubbles up to closest ancestor `not_found.*`). Receives `{ params }` plus props from `getProps` if present. |
101
104
 
@@ -118,39 +121,55 @@ Create an empty file (no extension) inside any route folder to alter layout inhe
118
121
  | `[slug]` | `src/blog/[slug]/page.tsx` | `/blog/hello` | `{ slug: string }` |
119
122
  | `[[slug]]` | `src/item/[[slug]]/page.tsx` | `/item`, `/item/42` | `{ slug?: string }` |
120
123
  | `[...slug]` | `src/docs/[...slug]/page.tsx` | `/docs/a/b/c` (1+ segments) | `{ slug: string[] }` |
121
- | `[[...slug]]` | `src/shop/[[...slug]]/page.tsx` | `/shop`, `/shop/a/b` (0+ segments) | `{ slug?: string[] }` |
124
+ | `[[...slug]]` | `src/shop/[[...slug]]/page.tsx` | `/shop`, `/shop/a/b` (0+ segments) | `{ slug: string[] }` (runtime `[]` on base; optional in `<Link params>` & `getStaticPaths`) |
122
125
  | `(group)` | `src/(marketing)/pricing/page.tsx` | `/pricing` | Organization group (omitted from URL). |
123
- | `_escaped` | `src/_legacy/page.tsx` | *(Ignored)* | Folders starting with `_` are ignored by the route scanner. |
126
+ | `_escaped` | `src/_legacy/page.tsx` | *(Excluded)* | Completely excluded from routing, bundlers, VFS, route types & Server Functions (`403`). Importing `src/_*` from active code fails at compile time (active helper folders like `src/components/` need no `_`). |
124
127
  | `@slot` | `src/dashboard/@analytics/page.tsx` | `/dashboard` | **Parallel Route Slot:** injected as prop `analytics` into `src/dashboard/layout.tsx`. Isolated error boundary per slot. |
125
128
 
126
- > **Strict No-Gap Rule:** Every intermediate route segment that has a `layout.tsx` or dynamic parameter along a branch should be properly structured; however, pass-through folders without `page.tsx` (e.g. `src/api/v1/users/page.tsx`) are supported and resolved in memory.
129
+ > **Specificity, Backtracking & Pass-Through Folders:** The router resolves competing branches deterministically using full multi-branch and `(group)` backtracking ordered by specificity (`static` > `[slug]` > `[[slug]]` > `[...slug]` > `[[...slug]]`), rejects literal router-syntax segments (`(group)`, `[param]`, `@slot`, `_private`) in URLs, and supports pass-through folders without `page.tsx` (e.g. `src/api/v1/users/page.tsx`).
127
130
 
128
- ### Compile-Time Type-Safe Routing (`.dinou/types/routes.d.ts`)
129
- Dinou automatically generates `.dinou/types/routes.d.ts` during `dev` and `build`. Include it in `tsconfig.json`:
131
+ ### Compile-Time Type-Safe Routing & Contextual `"./dinou"` Modules
132
+ Dinou generates `.dinou/types/routes.d.ts` and per-folder `.dinou/routes/<relDir>/dinou.{js,d.ts}` modules during `dev`, `build`, or `npx dinou typegen`. Configure `tsconfig.json` with `rootDirs`:
130
133
  ```json
131
134
  {
132
- "include": ["src", ".dinou/types/routes.d.ts"]
135
+ "compilerOptions": {
136
+ "target": "ES2022", "module": "ESNext", "moduleResolution": "bundler", "jsx": "react-jsx",
137
+ "strict": true, "noEmit": true, "skipLibCheck": true,
138
+ "rootDirs": ["src", ".dinou/routes"], "paths": { "@/*": ["./src/*"] }
139
+ },
140
+ "include": ["src", "dinou-env.d.ts", ".dinou/types/**/*.d.ts"]
133
141
  }
134
142
  ```
135
- Use the exported types from `"dinou"`:
136
- ```tsx
137
- import type { PageProps, LayoutProps, ErrorProps, PageFunctions, LayoutFunctions } from "dinou";
138
143
 
144
+ #### 1. Zero-Boilerplate Route-Contextual Imports (`from "./dinou"`)
145
+ Inside any route or `@slot` folder in `src/`, import from `"./dinou"`—or `"../dinou"` from a nested helper subfolder like `components/` (resolved via TS `rootDirs` and bundler plugins; defers to any user `dinou.*` file in `src/`). Segment contracts (`PageProps`, `LayoutProps` with auto-inferred `@slot` props, `SlotProps`, `ErrorProps`, `NotFoundProps`, `PageFunctions`, `LayoutFunctions`, `RouteParams`, `ROUTE`) and relative navigation (`<Link>`, `useRouter()`) are pre-bound to that folder:
146
+ ```tsx
139
147
  // src/blog/[slug]/page_functions.ts
140
- export const getProps: PageFunctions<"/blog/[slug]">["getProps"] = async (params) => {
148
+ import type { PageFunctions } from "./dinou";
149
+
150
+ export const getProps: PageFunctions["getProps"] = async (params) => {
141
151
  // params is typed as { slug: string }
142
152
  return { title: `Post ${params.slug}` };
143
153
  };
144
154
 
145
155
  // src/blog/[slug]/page.tsx
146
- export default async function BlogPage({
147
- params,
148
- title,
149
- }: PageProps<"/blog/[slug]"> & { title: string }) {
150
- return <h1>{title} ({params.slug})</h1>;
156
+ import { Link, type PageProps } from "./dinou";
157
+
158
+ export default async function BlogPage({ params, title }: PageProps<{ title: string }>) {
159
+ return (
160
+ <article>
161
+ <h1>{title} ({params.slug})</h1>
162
+ {/* Strict relative link (no `from` needed) & dynamic `params` interpolation */}
163
+ <Link to="comments">Comments</Link>
164
+ <Link to="/blog/[slug]" params={{ slug: "next-post" }}>Next</Link>
165
+ </article>
166
+ );
151
167
  }
152
168
  ```
153
169
 
170
+ #### 2. Explicit Global Imports (`from "dinou"` — Anywhere, Including `src/components/`)
171
+ Outside a specific route folder (or when using explicit route literals), pass the segment pattern to `"dinou"` generics (`PageProps<"/blog/[slug]", { title: string }>`, `LayoutProps<"/dashboard">` with auto-inferred `@slot` props, `SlotProps<"/dashboard/@analytics">`, `ErrorProps<"/blog/[slug]">`, `NotFoundProps<"/blog/[slug]">`, `PageFunctions<"/blog/[slug]">`, `LayoutFunctions<"/dashboard">`), and pass `from` for strict relative links (`<Link from="/blog/[slug]" to="comments" />` or `router.push("comments", { from: "/blog/[slug]" })`).
172
+
154
173
  ---
155
174
 
156
175
  ## 4. Route Lifecycles (`page_functions.ts` & `layout_functions.ts`)
@@ -160,12 +179,12 @@ Both `page_functions.ts` and `layout_functions.ts` share the `RouteSegmentConfig
160
179
  | Export | Signature / Type | Default | Behavior |
161
180
  | :--- | :--- | :--- | :--- |
162
181
  | `revalidate` | `number \| false \| (() => number \| false \| Promise<...>)` | `false` | **`false`**: Permanent SSG/ISG until on-demand invalidation.<br>**`0` (or `< 1`)**: Dynamic SSR on every request.<br>**`>= 1`**: Time-based ISR (TTL in seconds; stale-while-revalidate in background). |
163
- | `ppr` | `boolean \| (() => boolean \| Promise<boolean>)` | `false` (or global `dinou.config.mjs`) | Enables **Partial Prerendering** for this segment (static shell + streaming `<Suspense>` holes). |
182
+ | `ppr` | `boolean \| (() => boolean \| Promise<boolean>)` | `false` (or global `dinou.config.*`) | Enables **Partial Prerendering** strictly for **this segment** (no parent-to-child inheritance; falls back to `dinou.config.*`). |
164
183
  | `getCacheTags` | `string[] \| ((params) => string[] \| Promise<string[]>)` | `[]` | Tags associated with this page or layout segment for surgical invalidation via `revalidateTag(tag)`. |
165
- | `getProps` | `(params) => TProps \| Promise<TProps>` | `{}` | Server-only data loader. Returned object properties are spread directly as props onto `page.tsx` (and `not_found.tsx`) or `layout.tsx`. |
166
- | `getStaticPaths` | `StaticPathItem[] \| (() => StaticPathsResult)` | `[]` | *(Pages/Layouts)* Pre-generates paths at build time. Supports returning strings (`["a", "b"]`), numbers, string arrays for catch-all (`[["a", "b"]]`), or param objects (`[{ slug: "a" }]`). |
167
- | `validateParams` | `(params) => boolean \| Promise<boolean>` | `() => true` | Perimeter guard evaluated **before** `getProps` or rendering. Returning `false` halts execution and renders `not_found.tsx` with HTTP 404. In `layout_functions.ts`, protects the entire child subtree. |
168
- | `allowISG` | `boolean \| (() => boolean \| Promise<boolean>)` | `true` | When `true`, dynamic paths not returned by `getStaticPaths` are generated on-demand on first visit and cached (ISG). When `false`, unknown paths immediately return HTTP 404. |
184
+ | `getProps` | `(params) => TProps \| Promise<TProps>` | `{}` | Server-only loader; spreads props onto `page.tsx` (`not_found.tsx`) or `layout.tsx`. Un-awaited `Promise`/`Promise[]` values stream directly to `"use client"` `use(promise)` inside `<Suspense>` without blocking TTFB. |
185
+ | `getStaticPaths` | `StaticPathItem[] \| (() => StaticPathsResult)` | `[]` | Pre-generates paths at build time (`["a"]`, numbers, catch-all `[["a", "b"]]`, `undefined` for optional routes, or param objects `[{ slug: "a" }]`). |
186
+ | `validateParams` | `(params) => boolean \| Promise<boolean>` | `() => true` | Per-segment guard run **before** `getProps`/rendering (and before cached RSC delivery) root-to-child with accumulated `params`; returning `false` returns HTTP 404 across HTML, layout RSC, and page RSC. |
187
+ | `allowISG` | `boolean \| (() => boolean \| Promise<boolean>)` | `true` (or global `dinou.config.*`) | Per-segment ISG control: `true` caches unknown params on demand; `false` returns 404. Static layouts ignore `allowISG = false`; valid pre-rendered dynamic layouts preserve child `allowISG = true`. |
169
188
 
170
189
  ---
171
190
 
@@ -174,16 +193,9 @@ Both `page_functions.ts` and `layout_functions.ts` share the `RouteSegmentConfig
174
193
  Dinou features three orthogonal caching and rendering dimensions—**Horizontal**, **Vertical**, and **Temporal**—that work standalone or in **Triple Synergy**:
175
194
 
176
195
  ```
177
- ┌─────────────────────────────────────────────────────────────────────────┐
178
- │ 1. HORIZONTAL SEGMENTATION (HS) │
179
- │ Independent Layout Cache (layout.rsc) !== Page Cache (page.rsc) │
180
- ├─────────────────────────────────────────────────────────────────────────┤
181
- │ 2. VERTICAL SEGMENTATION (<DinouCacheSlot> Micro-ISR) │
182
- │ Sub-tree RSC payload cached & refreshed independently by ID or Tag │
183
- ├─────────────────────────────────────────────────────────────────────────┤
184
- │ 3. TEMPORAL SEGMENTATION — PARTIAL PRERENDERING (PPR) │
185
- │ Instant Static Shell (shell.html) + Streaming <Suspense> Holes │
186
- └─────────────────────────────────────────────────────────────────────────┘
196
+ 1. HORIZONTAL (HS) : Layout Cache (layout.rsc) !== Page Cache (page.rsc)
197
+ 2. VERTICAL (Slot) : <DinouCacheSlot> sub-tree RSC cached/refreshed by ID or Tag
198
+ 3. TEMPORAL (PPR) : Instant Static Shell (shell.html) + Streaming <Suspense> Holes
187
199
  ```
188
200
 
189
201
  ### 5.1. Dimension 1: Horizontal Segmentation (Layout vs. Page Isolation)
@@ -200,13 +212,13 @@ In Dinou, **`layout.tsx` (`layout_functions.ts`)** and **`page.tsx` (`page_funct
200
212
  #### Surgical Revalidation & Zero Hydration Mismatch (`Lazy HTML Re-Composition`):
201
213
  When you invalidate **only** a layout (`revalidateLayout("/dashboard")` or `revalidateTag("layout-tag")`):
202
214
  - Dinou regenerates **only** `layout.rsc` without re-executing child `page.tsx` components (preserving all cached child `page.rsc` payloads).
203
- - Whenever a hard request (`GET /dashboard/settings`) or F5 reload arrives and detects that the ancestor `layout.rsc` is newer than the child's cached `index.html`, Dinou **lazily re-composes `index.html`** from the fresh `layout.rsc` + the existing cached `page.rsc` (and synchronizes the hydration RSC payload). This guarantees **zero React hydration mismatch** on hard reloads without cascading page re-renders.
215
+ - On the next hard request or F5 reload, if an ancestor `layout.rsc` is newer than the cached `index.html`, Dinou **lazily re-composes `index.html`** from the fresh `layout.rsc` + cached `page.rsc`, guaranteeing **zero React hydration mismatch** without cascading page re-renders.
204
216
 
205
217
  ---
206
218
 
207
219
  ### 5.2. Dimension 2: Vertical Segmentation (`<DinouCacheSlot>` Micro-ISR)
208
220
 
209
- While Horizontal Segmentation isolates route segments (`layout.tsx` vs. `page.tsx`), **Vertical Segmentation** isolates individual component subtrees *inside* a layout or page. `<DinouCacheSlot>` (imported from `"dinou/server"`) caches an arbitrary React Server Component subtree independently from its host page or layout.
221
+ **Vertical Segmentation** isolates component subtrees *inside* a layout or page: `<DinouCacheSlot>` (`"dinou/server"`) caches any RSC subtree independently from its host.
210
222
 
211
223
  ```tsx
212
224
  import { DinouCacheSlot } from "dinou/server";
@@ -227,11 +239,11 @@ export default async function DashboardPage() {
227
239
  - **Props:**
228
240
  - `id?: string`: Explicit slot identifier (auto-derived if omitted, though explicit `id` is recommended for live client `refreshSlot`).
229
241
  - `tag?: string` / `tags?: string[]`: Semantic cache tags for `revalidateTag(tag)` and `refreshSlot(tag)`.
230
- - `revalidate?: number`: Slot TTL in seconds (`0` = never cached; `> 0` = time-based Micro-ISR; omitted = cached until invalidated).
242
+ - `revalidate?: number | false`: Slot TTL in seconds (`0` or `< 1` = never cached; `>= 1` = time-based Micro-ISR; `false` or omitted = cached until invalidated).
231
243
  - `children`: Either JSX (`<AsyncServerComponent />`) or a lazy factory function (`() => <AsyncServerComponent />`).
232
244
  - **Works in Both Dynamic & Static Hosts:**
233
245
  - Inside a **Dynamic Page (`revalidate = 0`)**: The host page re-renders on every request, while `<DinouCacheSlot>` subtrees hit cache without re-running their DB queries.
234
- - Inside a **Static Page (`revalidate = false` or `ppr = true` Static Shell)**: When a slot is invalidated via `revalidateTag(tag)`, Dinou updates the slot and re-composes the static host page/shell. When a Static Shell slot's `revalidate` TTL expires (`revalidate >= 1`), Dinou uses **non-blocking Background Stale-While-Revalidate (SWR)**: the incoming request serves the cached `index.html` / `shell.html` immediately (`0ms` TTFB) while regenerating the expired `slot.json` and recomposing the host HTML/RSC in the background.
246
+ - Inside a **Static Page (`revalidate = false` or `ppr = true` Static Shell)**: `revalidateTag(tag)` updates the slot and re-composes the static host/shell. On TTL expiry (`revalidate >= 1`), Dinou uses **non-blocking Background SWR**: serving cached `index.html`/`shell.html` immediately (`0ms` TTFB) while regenerating `slot.json` and recomposing host HTML/RSC in the background.
235
247
  - **Nested `<DinouCacheSlot>` Isolation:** A `<DinouCacheSlot>` can contain inner `<DinouCacheSlot>` components. Invalidating or refreshing the **inner** slot re-evaluates **only** the inner slot while the outer slot stays cached.
236
248
  - **Client Components & Server Action Props Inside Slots:** `<DinouCacheSlot>` subtrees can render `"use client"` components and pass `"use server"` functions as props; Dinou preserves client reference manifests and action bindings across slot serialization.
237
249
  - **Stampede Protection:** Concurrent cache-miss requests for the same slot key are deduplicated in-flight onto a single render promise.
@@ -245,18 +257,17 @@ export default async function DashboardPage() {
245
257
 
246
258
  ### 5.3. Dimension 3: Temporal Segmentation — Partial Prerendering (PPR)
247
259
 
248
- **Partial Prerendering (PPR)** is Dinou's **Temporal Segmentation** axis: it splits a single route across *time*, delivering the pre-rendered **Static Shell (`shell.html`)** at $t = 0\text{ ms}$ (build/revalidation time) while streaming personalized or live **`<Suspense>` Dynamic Holes** concurrently at request time over the same HTTP connection.
260
+ **Partial Prerendering (PPR)** is Dinou's **Temporal Segmentation** axis: it splits a single route across *time*, delivering the pre-rendered **Static Shell (`shell.html`)** at `t = 0ms` (build/revalidation time) while streaming personalized or live **`<Suspense>` Dynamic Holes** concurrently at request time over the same HTTP connection.
249
261
 
250
- Enable PPR globally in `dinou.config.mjs` (`ppr: true`) or per-route/layout in `page_functions.ts` / `layout_functions.ts` (`export const ppr = true`).
262
+ Enable PPR globally (`dinou.config.*` `ppr: true`) or per-segment (`export const ppr = true | false` in `page_functions.ts` / `layout_functions.ts`). **`ppr` is strictly per-segment with zero parent-to-child inheritance** (falling back to `dinou.config.*`, default `false`), supporting mixed-PPR chains (e.g. `ppr = false` layout -> `ppr = true` nested layout -> `ppr = false` page) in isolated scopes.
251
263
 
252
264
  #### How `<Suspense>` Boundaries, Dynamic PPR Holes & `noDynamic()` Work:
253
265
  1. **`<Suspense>` Is the Single Boundary (`ppr = true` vs. `ppr = false`):**
254
- - **Outside `<Suspense>`** (top-level `async` Page/Layout, `getProps`, or unwrapped child `async` Server Components): Awaited at build/revalidation time and baked directly into the **Static Shell (`shell.html`)**. *(Accessing `req.cookies`, `req.headers`, `req.query`, or `<DinouCacheSlot revalidate={0}>` outside `<Suspense>` triggers a Full-Page Dynamic Bailout).*
255
- - **Inside `<Suspense fallback={...}>` (Default = Dynamic PPR Hole):** On `ppr = true` routes, **any `async` Server Component** (postponed immediately at its first `await` with zero build latency), any component reading `getContext()` (`req.cookies`, `req.headers`, `req.query`) / `useSearchParams()`, or `<DinouCacheSlot revalidate={0}>` automatically becomes a **Dynamic PPR Hole** (`data-ppr-hole`). Its `<Suspense>` fallback is baked into `shell.html` (`0ms` TTFB) and the resolved content streams live over the same HTTP response at request time. *(On `ppr = false` routes, `async` components inside `<Suspense>` resolve at build time into `index.html`).*
256
- 2. **Static `<Suspense>` Opt-Out via `noDynamic()` (`"dinou"` or `"dinou/server"`):**
257
- - If an `async` Server Component inside `<Suspense>` on a `ppr = true` route should instead resolve at build time into the **Static Shell (`shell.html`)** (e.g., static Markdown/syntax highlighting), call **`noDynamic()`** synchronously at the top of the component **before its first `await`**.
258
- - At runtime, leaf static `<Suspense>` boundaries opted out via `noDynamic()` automatically short-circuit (`0ms`, zero re-execution) when sibling dynamic holes stream. *(If `req.cookies`, `req.headers`, or `req.query` is read inside a `noDynamic()` subtree, dynamic bailout always wins).*
259
- 3. **Single-Request Streaming:** On incoming HTTP requests, Dinou flushes the cached `shell.html` immediately and concurrently streams all Dynamic PPR Holes over the same HTTP response stream. If a `ppr = true` route has zero dynamic holes (`holes: []`), Dinou serves `shell.html` directly with zero runtime component execution.
266
+ - **Outside `<Suspense>`** (top-level `async` Page/Layout, `getProps`, or unwrapped `async` RSCs): Awaited at build/revalidation time and baked into `shell.html`. *(Reading `req.cookies`/`headers`/`query`, calling `useSearchParams()` in an RSC, or rendering `<DinouCacheSlot revalidate={0}>` outside `<Suspense>` triggers a Full-Page Dynamic Bailout).*
267
+ - **Inside `<Suspense fallback={...}>` (Default = Dynamic PPR Hole):** On `ppr = true` segments, any `async` RSC (postponed at its first `await`), any `"use client"` component with an un-awaited `Promise`/`Promise[]` prop, any RSC reading `req.cookies`/`headers`/`query` or `useSearchParams()`, or `<DinouCacheSlot revalidate={0}>` becomes a **Dynamic PPR Hole** (`data-ppr-hole`): fallback baked into `shell.html` (`0ms` TTFB), live content streamed per request. *(`"use client"` `useSearchParams()` stays in the Static Shell with zero `#418` hydration mismatch. On `ppr = false` segments, `<Suspense>` resolves statically into `index.html`).*
268
+ 2. **Static `<Suspense>` Opt-Out via `noDynamic()` (`"dinou"` / `"dinou/server"`):**
269
+ - Call **`noDynamic()`** synchronously at the top of an `async` RSC inside `<Suspense>` (before its first `await`) to bake it into `shell.html` at build time and short-circuit (`0ms`) at runtime. *(Reading `req.cookies`/`headers`/`query` inside `noDynamic()` still triggers dynamic bailout).*
270
+ 3. **Single-Request Streaming:** Dinou flushes `shell.html` immediately and streams all Dynamic PPR Holes over the same HTTP response. With zero holes (`holes: []`), `shell.html` is served directly with zero runtime execution.
260
271
 
261
272
  ---
262
273
 
@@ -268,15 +279,18 @@ All three dimensions compose simultaneously in the same route tree:
268
279
  - **`<DinouCacheSlot>` Outside `<Suspense>` (or Wrapping an Inner `<Suspense>`)**: Resolves at build time into the **Static Shell (`shell.html` + `slot.json`)**, preserving any inner `<Suspense>` node in `slot.json` and using non-blocking background SWR upon TTL expiration.
269
280
  - **`<Suspense>` Wrapping `<DinouCacheSlot>` (`<Suspense><DinouCacheSlot>...</DinouCacheSlot></Suspense>`)**: Acts as a **Cached Dynamic PPR Hole** by default on `ppr = true` routes (unless opted out via `noDynamic()`), baking the `<Suspense>` fallback into `shell.html` and caching `slot.json` across runtime hole streams.
270
281
  - **Synergy Invalidation Invariants:**
271
- 1. Invalidating a `<DinouCacheSlot>` inside a **PPR Dynamic Hole** (`revalidateTag("hole-slot")`) updates only that slot on the next request without regenerating `shell.html` or sibling slots.
272
- 2. Invalidating a `<DinouCacheSlot>` inside a **PPR Static Shell** (`revalidateTag("shell-slot")`) purges the slot and automatically enqueues background regeneration of the host `shell.html` (and `layout.rsc` if the slot lives in the layout shell), while leaving sibling cached slots untouched.
273
- 3. Calling `refreshSlot(idOrTag, { fresh: true })` (or `refreshSlot("*", { fresh: true })`) from the browser updates slots live in the DOM across the Layout Shell, Layout Holes, Page Shell, and Page Holes simultaneously, **and** enqueues background regeneration of any affected static shells so a subsequent F5 hard reload serves the exact updated slot tokens with **zero hydration mismatch**.
282
+ 1. `revalidateTag("hole-slot")` for a slot inside a **PPR Dynamic Hole** updates only that slot without regenerating `shell.html` or sibling slots.
283
+ 2. `revalidateTag("shell-slot")` for a slot inside a **PPR Static Shell** purges the slot and enqueues background regeneration of `shell.html` (and `layout.rsc` if in a layout shell) without touching sibling slots.
284
+ 3. `refreshSlot(idOrTag | "*", { fresh: true })` updates mounted slots live across Layout/Page Shells & Holes and enqueues background shell regeneration so F5 reloads match with zero hydration mismatch.
285
+ - **Single-Pass Inline RSC Streaming & Scoped `useId()`:**
286
+ - Dynamic SSR, PPR resumes, and first-time ISG renders evaluate layouts and page **once per request** and stream Flight payloads inline (`__DINOU_RSC_L__` / `__DINOU_RSC_P__`), preventing extra `/____rsc_*` round-trips and `#418` mismatches.
287
+ - Sync and `async` RSCs support `useId()` (plus `useMemo`/`useCallback`) with collision-free IDs scoped per segment (`_layout_`, `_page_`, `_slot_`, `_hole_`).
274
288
 
275
289
  ---
276
290
 
277
291
  ## 6. Client Navigation, Router Cache & Hooks
278
292
 
279
- Import navigation primitives from `"dinou"`:
293
+ Import navigation primitives from `"dinou"` (or from route-contextual `"./dinou"` inside route folders to pre-bind `from` for relative targets):
280
294
 
281
295
  ```tsx
282
296
  "use client";
@@ -294,44 +308,47 @@ import {
294
308
 
295
309
  | Primitive | Scope | Signature / Props | Key Behavior |
296
310
  | :--- | :--- | :--- | :--- |
297
- | `<Link>` | Universal | `href` (or `to`), `prefetch?: boolean` (`true`), `fresh?: boolean` (`false`) | Performs soft SPA navigation. Prefetches RSC payload on hover when `prefetch={true}`. Pass `fresh` to bypass the client-side router cache (`pageCache`). Supports relative paths (`"sub"`, `"../other"`). |
298
- | `useRouter()` | Client | `{ push, replace, back, forward, refresh, refreshSlot }` | `push(href, { fresh? })`, `replace(href, { fresh? })`, `refresh({ layout?: boolean })` (re-fetches current page RSC payload; pass `{ layout: true }` to also re-fetch layouts), `refreshSlot(idOrTag, { fresh? })`. |
311
+ | `<Link>` | Universal | `href` (or `to`), `params?`, `from?`, `prefetch?: boolean` (`true`), `fresh?: boolean` (`false`) | Soft SPA navigation; hover RSC prefetch (`prefetch`); `fresh` bypasses `pageCache`. Interpolates `[param]`/`[[param]]`/`[...slug]`/`[[...slug]]` via `params` and validates/resolves relative paths (`"sub"`, `"./sub"`, `"../other"`) via `from` (pre-bound in `"./dinou"`). |
312
+ | `useRouter()` | Client | `{ push, replace, back, forward, refresh, refreshSlot }` | `push`/`replace(href, { fresh?, params?, from? })` (`from` pre-bound in `"./dinou"`), `refresh({ layout?: boolean })` (page RSC, or layout + page when `layout: true`), `refreshSlot(idOrTag, { fresh? })`. |
299
313
  | `usePathname()` | Universal | `() => string` | Returns current URL pathname (e.g. `"/blog/hello"`). Works in both Server Components and Client Components. |
300
- | `useSearchParams()` | Universal | `() => URLSearchParams` | Returns read-only `URLSearchParams`. Works in both Server Components (triggers dynamic/PPR bailout) and Client Components. |
314
+ | `useSearchParams()` | Universal | `() => URLSearchParams` | Read-only `URLSearchParams`. **Server Components:** reads `ctx.req.query` (PPR hole inside `<Suspense>` on `ppr = true`; dynamic bailout outside `<Suspense>`). **Client Components:** stays in Static/PPR Shell, hydrates empty via `useSyncExternalStore` (zero `#418`), then syncs with live URL. |
301
315
  | `useNavigationLoading()` | Client | `() => boolean` | Returns `true` while a client-side route transition is in flight. |
302
- | `redirect(url)` | Universal | `(destination: string) => ReactNode` | In `getProps` or Server Functions/Components before headers flush: sends real HTTP `307 Temporary Redirect` (or `X-Dinou-Redirect` in RPC). If streaming has already started or on client: renders `<ClientRedirect to={destination} />`. |
316
+ | `redirect(url)` | Universal | `(destination: string) => ReactNode` | In `getProps` or Server Functions/Components before headers flush: sends real HTTP `302 Found` (or `x-rsc-redirect` on soft RSC navigation) and short-circuits rendering. If streaming has already started or on client: renders `<ClientRedirect to={destination} />`. |
303
317
  | `<ClientRedirect>` | Client | `<ClientRedirect to="/login" />` | Triggers immediate client-side `replace` navigation upon mount. |
304
- | `refreshSlot()` | Client | `(slotIdOrTag: string, opts?: { fresh?: boolean }) => void` | Standalone helper (identical to `useRouter().refreshSlot`) to refresh one or all (`"*"`) `<DinouCacheSlot>` instances live in the browser. |
318
+ | `refreshSlot()` | Client | `(slotIdOrTag: string, opts?: { fresh?: boolean }) => Promise<void>` | Standalone helper (identical to `useRouter().refreshSlot`) to refresh one or all (`"*"`) `<DinouCacheSlot>` instances live in the browser; resolves once refreshes settle. |
305
319
 
306
320
  ---
307
321
 
308
322
  ## 7. Server Functions (`"use server"`), Context & The Dinou Pattern
309
323
 
310
324
  ### Server Functions & Actions (`"use server"`)
311
- Any file or async function marked with `"use server"` runs exclusively on the server and can be imported directly into Client Components (`"use client"`):
325
+ Any file or async function marked with `"use server"` runs exclusively on the server and can be passed to or imported directly into Client Components (`"use client"`):
326
+ - **Three Supported Scopes:** (1) Module-level `"use server"` files, (2) Function-body `"use server"` inside mixed utility files (granular manifest tree-shaking exposes only marked functions while allowing direct `"use client"` imports), and (3) Inline `"use server"` functions defined inside Server Components (including lexical closure capture).
312
327
  - Supports standard React 19 form actions (`<form action={myAction}>`, `useActionState`, `useFormStatus`, `useOptimistic`) and direct RPC calls (`await myAction(arg1, arg2)`), including `FormData` uploads.
313
328
  - **Security:** Bundlers automatically strip the implementation from the client bundle and replace it with a Flight RPC proxy (`/____server_function____`).
314
329
 
315
330
  ### Reading & Mutating Request Context (`getContext()`)
316
- Call `getContext()` (from `"dinou"` or `"dinou/server"`) synchronously inside any Server Component, `getProps`, `validateParams`, or `"use server"` function:
331
+ Call `getContext()` (from `"dinou"`, `"dinou/server"`, or contextual `"./dinou"`) synchronously inside any Server Component, `page_functions.ts` / `layout_functions.ts`, `plugin.onRequest`, or `"use server"` function (always returns a non-nullable `RequestContextStore` on the server with `env` populated):
317
332
  ```ts
318
333
  import { getContext } from "dinou";
319
334
 
320
335
  export async function updateThemeAction(theme: string) {
321
336
  "use server";
322
- const ctx = getContext();
323
- if (!ctx) return; // undefined during static build time if no request is active
337
+ const { req, res } = getContext();
324
338
 
325
- const currentCookie = ctx.req.cookies["theme"];
326
- const userAgent = ctx.req.headers["user-agent"];
339
+ const currentCookie = req.cookies["theme"];
340
+ const userAgent = req.headers["user-agent"];
327
341
 
328
- ctx.res.cookie("theme", theme, { path: "/", httpOnly: true, maxAge: 86400 });
329
- ctx.res.setHeader("X-Custom-Header", "updated");
342
+ res.cookie("theme", theme, { path: "/", httpOnly: true, maxAge: 86400 });
343
+ res.setHeader("X-Custom-Header", "updated");
330
344
  }
331
345
  ```
332
- - `ctx.req`: `{ query, cookies, headers, path, method, env, ctx }`
346
+ - `ctx.req`: `{ query, cookies, headers, path, rawPath, isRscRequest, method, env, ctx }` (`req.path` is normalized even on internal `/____rsc_*` SPA fetches).
333
347
  - `ctx.res`: `{ cookie(name, val, opts?), clearCookie(name, opts?), setHeader(name, val), status(code), redirect(statusOrUrl, url?) }`
334
- - `ctx.env` / `ctx.ctx`: Platform bindings (e.g., Cloudflare Workers `env.DB`, `env.KV`, `ctx.waitUntil`).
348
+ - `ctx.env` / `ctx.ctx`: Unified zero-copy `DinouEnv` proxy across Cloudflare bindings (`env.DB`, `env.KV`, `env.R2`, secrets), `Netlify.env`, `process.env`, and `Deno.env`, plus platform context (`ctx.waitUntil`).
349
+
350
+ ### Server-to-Client Promise Streaming (`use(promise)`)
351
+ Server Components and `getProps()` can pass raw, un-awaited `Promise` (or `Promise[]`) props directly to `"use client"` components wrapped in `<Suspense>`, streaming resolution over React Flight to React 19's `use(promise)` on the client without blocking TTFB (and registering a Dynamic PPR Hole automatically on `ppr = true` segments).
335
352
 
336
353
  ### The Dinou Pattern (Streaming Server Components from Server Functions)
337
354
  In Dinou, a `"use server"` function can return **rendered JSX (including async Server Components and `<Suspense>` trees)** directly to a Client Component over React Flight RPC:
@@ -381,36 +398,37 @@ await revalidateLayout("/dashboard"); // Purges only layout.rsc (preserves c
381
398
 
382
399
  ---
383
400
 
384
- ## 8. Configuration (`dinou.config.mjs`), Middleware (`onRequest`) & Storage Adapters
401
+ ## 8. Configuration (`dinou.config.ts`), Middleware (`onRequest`) & Storage Adapters
385
402
 
386
- Create `dinou.config.mjs` (or `.js` / `.ts`) at the project root using `defineConfig` from `"dinou"` (or `"dinou/config"`):
403
+ Create `dinou.config.ts` (or `.mjs` / `.js` / `.cjs`) at the project root using `defineConfig` from `"dinou"` (or `"dinou/config"`). Config files and plugins are compiled AOT into every production bundle (zero runtime `esbuild` dependency) and hot-reload in `dinou dev`:
387
404
 
388
- ```js
405
+ ```ts
389
406
  import { defineConfig } from "dinou";
390
407
  import { RedisStorage } from "dinou/server";
391
408
 
392
409
  export default defineConfig({
393
- reactStrictMode: true, // Default: true
394
- ppr: false, // Global PPR default (can be overridden per route/layout)
395
- setupFiles: ["./dinou.setup.ts"],
396
- // storage: new RedisStorage(redisClient, "dinou:"),
410
+ reactCompiler: true, // Default: true (babel-plugin-react-compiler across Esbuild, Rollup & Webpack prod builds)
411
+ reactStrictMode: true, // Default: true (dev only)
412
+ ppr: false, // Global PPR default per segment (overridable in page_functions / layout_functions)
413
+ allowISG: true, // Global ISG default for dynamic segments (set false for strict SSG-only 404 mode)
414
+ assetExtensions: ["glb"], // Optional extra static binary/media extensions (auto-typed by dinou typegen)
415
+ setupFiles: ["@/polyfills"], // Runs once at Line 1 before modules load (supports tsconfig aliases)
416
+ // storage: new RedisStorage(redisClient, { prefix: "dinou:", hydrateFromDisk: true }),
397
417
  plugins: [
398
418
  {
399
419
  name: "auth-and-webhooks",
400
- // 1. Universal Web Standards HTTP Middleware & Webhook Handler
420
+ // 1. Universal Web Standards HTTP Middleware & Webhook Handler (skipped during build-time SSG)
401
421
  async onRequest(request, context) {
402
- const url = new URL(request.url);
403
-
404
- // Short-circuit webhooks or API endpoints (<2ms, bypasses React)
405
- if (url.pathname === "/api/health") {
406
- return Response.json({ ok: true });
422
+ // context.req.path is normalized even on SPA /____rsc_* fetches
423
+ if (context.req.path === "/api/health" && request.method === "GET") {
424
+ return Response.json({ ok: true }); // Short-circuits React rendering (<2ms)
407
425
  }
408
426
 
409
427
  // Mutate context for downstream Server Components & Server Functions
410
428
  context.user = { id: request.headers.get("x-user-id") ?? "guest" };
411
429
  },
412
430
 
413
- // 2. Optional Node.js HTTP Server Hook (WebSockets, raw Node middleware)
431
+ // 2. Optional Node.js HTTP Server Hook (WebSockets, Socket.IO, Connect/Express middleware)
414
432
  configureServer({ server, isDev, use }) {
415
433
  use((req, res, next) => {
416
434
  res.setHeader("X-Powered-By", "Dinou");
@@ -423,53 +441,52 @@ export default defineConfig({
423
441
  ```
424
442
 
425
443
  ### Pluggable ISR Storage Adapters (`"dinou/server"`)
426
- - `FileSystemStorage(baseDir?)`: Default on Node.js & Bun (persists to `.dinou/cache`).
427
- - `CloudflareKVStorage(kvNamespace)`: Default on Cloudflare Workers when `env.DINOU_CACHE` KV binding is present.
428
- - `DenoKVStorage(kvInstance?)`: Default on Deno / Deno Deploy.
429
- - `MemoryStorage()`: In-memory fallback when no persistent store is configured.
430
- - `RedisStorage(redisClient, prefix?)`: Distributed cluster cache for multi-instance deployments.
431
- - Custom adapter: extend `StorageAdapter` (`get(key)`, `set(key, content, metadata?)`, `has(key)`, `delete(key)`) or call `setStorageAdapter(adapter)`.
444
+ - `FileSystemStorage(baseDir?)`: Default on Node.js, Bun & Deno (persists to `.dinou/dist2`).
445
+ - `CloudflareKVStorage(kvNamespace)`: Default on Cloudflare Workers when `env.DINOU_CACHE` KV binding is present (with cursor-paginated `keys()`).
446
+ - `DenoKVStorage(kvInstance?)`: Default on Deno / Deno Deploy when Deno KV is available.
447
+ - `MemoryStorage({ hydrateFromDisk? })`: Default on Netlify Functions v2 (`hydrateFromDisk: true`) and isolated unit tests (`hydrateFromDisk: false`).
448
+ - `RedisStorage(redisClient, prefixOrOptions?)`: Distributed cluster cache (`node-redis`, `ioredis`, Upstash) with cluster tombstones & tag invalidation timestamps.
449
+ - Custom adapter: extend `StorageAdapter` (`get(key)`, `set(key, content, metadata?)`, `has(key)`, `delete(key)`, optional `keys(prefix?)`) or call `setStorageAdapter(adapter)`.
432
450
 
433
451
  ---
434
452
 
435
453
  ## 9. Styling, Assets, Environment Variables & Aliases
436
454
 
437
- - **Global CSS & Tailwind CSS v4:** Import `./styles.css` in `src/layout.tsx` (compiled automatically via PostCSS + `@tailwindcss/postcss` + `autoprefixer` into `/styles.css`) and link it in `<head>`:
455
+ - **Global CSS & Tailwind CSS v4:** Import `./styles.css` in `src/layout.tsx` (compiled automatically via PostCSS + `@tailwindcss/postcss` + `autoprefixer` into `/styles.css`, minified in production across all 3 bundlers) and link it in `<head>`:
438
456
  ```tsx
439
457
  import "./styles.css";
440
458
  // Inside RootLayout <head>:
441
459
  <link rel="stylesheet" href="/styles.css" precedence="default" />
442
460
  ```
443
- - **CSS Modules:** Any `*.module.css` file returns scoped class names (`import styles from "./card.module.css"`).
444
- - **Media & Asset Imports:** Import 21+ formats (`.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`, `.avif`, `.ico`, `.mp4`, `.webm`, `.ogg`, `.mp3`, `.wav`, `.flac`, `.aac`, `.woff`, `.woff2`, `.eot`, `.ttf`, `.otf`, `.pdf`) directly in Server or Client Components to receive their hashed public URL string. Add `/// <reference types="dinou/env" />` in `src/env.d.ts` for TypeScript support.
445
- - **Public Directory (`public/`):** Files in `public/` are copied verbatim to `.dinou/dist3/` and served at the root URL (`/favicon.ico`, `/robots.txt`).
446
- - **Path Aliases (`tsconfig.json`):** Configure `compilerOptions.paths` (e.g. `"@/*": ["./src/*"]`) in `tsconfig.json`. Dinou automatically resolves aliases across TypeScript/JSX, CSS `@import`, and asset imports in all three bundlers (esbuild, Rollup, Webpack).
447
- - **Environment Variables:** `.env` files are loaded on the server via `dotenv`. For security, `process.env` secrets are **server-only** and never bundled into client code; pass public values explicitly as props from Server Components to Client Components.
461
+ - **CSS Modules & `url(...)`:** Any `*.module.css` works natively in both Server Components (RSC) and Client Components with zero hydration mismatches; relative/aliased CSS `url(...)` assets fingerprint into `/assets/[name]-[hash].[ext]`.
462
+ - **Media & Asset Imports:** 26 built-in extensions (8 image, 7 video, 6 audio, 5 font formats) plus custom `assetExtensions` in `dinou.config.*`, content+path hashed to `/assets/[name]-[hash].[ext]`; reference `dinou/env` in `dinou-env.d.ts` for TS types.
463
+ - **Public Directory (`public/`):** Unhashed root static files (`/favicon.ico`, `/robots.txt`, `/sitemap.xml`, `/manifest.json`, `/.well-known/*`, `/llms.txt`) copied to `.dinou/dist3/` with RFC 9110 `206` byte-range streaming and dotfile/`.env*` protection (`404`).
464
+ - **Path Aliases (`tsconfig.json` / `jsconfig.json`):** Full `paths`, `baseUrl`, recursive `extends`, and `${configDir}` resolution across TS/JSX, CSS `@import`/`url(...)`, `setupFiles`, `dinou.config.ts`, and assets in all 3 bundlers with dev hot-reload.
465
+ - **Environment Variables & `DINOU_PUBLIC_*`:** Native `.env.<NODE_ENV>.local` → `.env.local` → `.env.<NODE_ENV>` → `.env` hierarchy (OS vars win; dev hot-reload; auto-typed `NodeJS.ProcessEnv`). Unprefixed `process.env.*` evaluates to `undefined` in `"use client"`; `DINOU_PUBLIC_*` inlines at build time across all bundlers/runtimes. On the server, prefer `getContext().env` for Node, Bun, Deno, Cloudflare (KV/D1/R2), and Netlify parity.
448
466
 
449
467
  ---
450
468
 
451
- ## 10. Bundlers, Deployment Targets, Dual-Mode Vendoring & Eject
469
+ ## 10. Bundlers, Deployment Targets, Dual-Mode Vendoring & Eject / Uneject
452
470
 
453
- ### Multi-Bundler Parity
454
- Dinou provides 100% feature parity across three bundlers:
455
- - **esbuild** (Default): Fastest builds and HMR.
471
+ ### Multi-Bundler Parity & React Compiler
472
+ Dinou provides 100% feature parity across three bundlers—with **`babel-plugin-react-compiler` enabled by default in production across all three** (toggle via `reactCompiler` in `dinou.config.*` or opt out locally with `"use no memo"`):
473
+ - **esbuild** (Default): Fastest builds and HMR (SWC disk cache + Esbuild).
456
474
  - **Rollup** (`:rollup`): Clean ES module output.
457
- - **Webpack** (`:webpack`): Includes `babel-plugin-react-compiler` automatic memoization in production builds.
475
+ - **Webpack** (`:webpack`): Full Webpack 5 ecosystem compatibility.
458
476
 
459
477
  ### Deployment Targets
460
- - **Node.js:** `npm run build && npm start` (entry: `dinou/adapters/node`).
461
- - **Cloudflare Workers:** `npm run build:cloudflare && npx wrangler deploy` (generates `.dinou/cloudflare/worker.js`).
462
- - **Bun:** `npm run build:bun && npm run start:bun` (or `npm run build:bun:compile` for standalone binary).
463
- - **Deno:** `npm run build:deno && npm run start:deno` (or `npm run build:deno:compile` for standalone binary).
464
- - **Netlify:** Uses `dinou/adapters/netlify` serverless entry.
465
- - **Static Export:** `npm run export-static` outputs a self-contained static site into `dist/`.
478
+ - **Node.js:** `npm run build && npm start` (emits `.dinou/node/server.mjs`; standalone binaries via `build:node:compile` / `build:node:pure:compile`).
479
+ - **Netlify Functions v2:** `npm run build:netlify` (or `npm run build`) emits a self-contained AOT bundle at `.dinou/netlify/functions/ssr.mjs` (`publish = ".dinou/dist3"`, `included_files = [".dinou/dist2/**"]`).
480
+ - **Cloudflare Workers:** `npm run build:cloudflare && npx wrangler deploy` (emits `.dinou/cloudflare/worker.js` + `[assets] directory = ".dinou/cloudflare/assets"`, `run_worker_first = true`, `html_handling = "none"`).
481
+ - **Bun:** `npm run build:bun && npm run start:bun` (or `build:bun:compile` / `build:bun:pure:compile` → `dist/server`).
482
+ - **Deno:** `npm run build:deno && npm run start:deno` (or `build:deno:compile` → `dist/deno-server`).
483
+ - **Static Export (SPA):** `npm run export-static` exports standalone HTML + `.rsc` SPA navigation payloads + static assets into `out/`.
466
484
 
467
485
  ### Dual-Mode Vendoring (`--unvendorized` / `-u`)
468
- By default, Dinou runs in **Vendorized Mode**, resolving Babel, PostCSS, Tailwind, Rollup/Webpack plugins, `ws`, `chokidar`, etc. from pre-compiled zero-install bundles in `dinou/compiled/` via `package.json` `#imports`.
469
- Pass `-u` / `--unvendorized` (e.g. `npx dinou dev -u` or `DINOU_UNVENDORIZED=true`) to resolve those packages from standard `node_modules` via Node's `--conditions=unvendorized`.
486
+ By default, Dinou runs in **Vendorized Mode**, resolving 31 pre-compiled zero-drift toolchain bundles from `dinou/compiled/` via `package.json` `#imports`. Pass `-u` / `--unvendorized` (e.g. `npm run dev -- -u`, `npx dinou build -u`, or `DINOU_UNVENDORIZED=true`) to resolve those packages directly from `node_modules` via `--conditions=unvendorized`.
470
487
 
471
- ### Ejecting (`npx dinou eject`)
472
- Running `npx dinou eject` copies the complete Dinou framework into `./dinou` at your project root and rewrites `package.json` scripts and imports to use `./dinou/index.js`, `./dinou/server.js`, and `./dinou/cli.js`, giving you 100% ownership of the compiler and runtime.
488
+ ### Reversible Eject & Uneject (`dinou eject` / `npm run uneject`)
489
+ `npx dinou eject` copies Dinou into `./dinou`, selectively rewrites existing Dinou scripts in `package.json`, adds `"build:vendors"` and `"uneject"`, and links `"dinou": "file:./dinou"` (user `"dinou"` imports stay untouched). Run `npm run uneject` (or `npm run uneject -- <version>`) anytime to transactionally restore `package.json`, reinstall `dinou` (with automatic rollback on failure), and remove `./dinou`.
473
490
 
474
491
  ---
475
492
 
@@ -478,18 +495,26 @@ Running `npx dinou eject` copies the complete Dinou framework into `./dinou` at
478
495
  ### Package `"dinou"`
479
496
  | Export | Kind | Description |
480
497
  | :--- | :--- | :--- |
481
- | `Link` | Component | Client SPA navigation `<Link href="..." prefetch? fresh? />` |
498
+ | `Link` | Component | Client SPA navigation `<Link href/to="..." params? from? prefetch? fresh? />` |
482
499
  | `ClientRedirect` | Component | Client mount redirect `<ClientRedirect to="..." />` |
483
- | `redirect` | Function | Universal redirect `redirect("/path")` (HTTP 307 or SPA redirect) |
484
- | `useRouter` | Hook (Client) | `{ push, replace, back, forward, refresh, refreshSlot }` |
500
+ | `redirect` | Function | Universal redirect `redirect("/path")` (HTTP 302, SPA `x-rsc-redirect`, or `<ClientRedirect />`) |
501
+ | `useRouter` | Hook (Client) | `{ push, replace, back, forward, refresh, refreshSlot }` (referentially stable) |
485
502
  | `usePathname` | Hook (Universal) | Current URL pathname string |
486
- | `useSearchParams` | Hook (Universal) | Current `URLSearchParams` |
503
+ | `useSearchParams` | Hook (Universal) | Current `URLSearchParams` (Server: dynamic/PPR hole; Client: zero-`#418` hydration sync) |
487
504
  | `useNavigationLoading` | Hook (Client) | Boolean pending navigation state |
488
- | `refreshSlot` | Function (Client) | `refreshSlot(slotIdOrTag, { fresh?: boolean })` (supports `"*"` wildcard) |
489
- | `getContext` | Function (Server) | Returns `{ req, res, env, ctx, ...custom }` from `AsyncLocalStorage` |
505
+ | `refreshSlot` | Function (Client) | `refreshSlot(slotIdOrTag, { fresh?: boolean }): Promise<void>` (supports `"*"` wildcard) |
506
+ | `getContext` | Function (Server) | Returns `{ req, res, env, ctx, ...custom }` (`RequestContextStore`) from `AsyncLocalStorage` |
490
507
  | `noDynamic` | Function (Server) | Opts enclosing `<Suspense>` out of becoming a Dynamic PPR Hole on `ppr = true` routes |
491
- | `defineConfig` | Function | Type-safe helper for `dinou.config.mjs` |
492
- | `PageProps<T>`, `LayoutProps<T>`, `ErrorProps<T>`, `PageFunctions<T, P>`, `LayoutFunctions<T, P>`, `RouteSegmentConfig`, `PPRConfig`, `StaticPathItem`, `StaticPathsResult`, `RouteParams<T>`, `DinouRoute`, `DinouRoutePattern`, `DinouRouter`, `CleanRoutePath`, `ExtractRouteParams`, `ExtractSegmentParam`, `LinkProps`, `ClientRedirectProps`, `NavigationOptions`, `RequestContextStore`, `ResponseProxy`, `CookieOptions`, `Query`, `Cookies`, `Headers`, `DinouConfig`, `DinouPlugin`, `ServerHookContext`, `NodeMiddleware` | TypeScript Types | Complete compile-time routing, component prop, context, and plugin types |
508
+ | `defineConfig` | Function | Type-safe helper for `dinou.config.{ts,mjs,js,cjs}` |
509
+ | `PageProps<T, P>`, `LayoutProps<T, P>`, `SlotProps<T>`, `ErrorProps<T>`, `NotFoundProps<T, P>`, `PageFunctions<T, P>`, `LayoutFunctions<T, P>`, `RouteSegmentConfig`, `PPRConfig`, `StaticPathItem`, `StaticPathsResult`, `RouteParams<T>`, `LayoutParams<T>`, `LayoutSlots<T>`, `SlotParams<T>`, `ErrorParams<T>`, `DinouRoute`, `DinouLinkTarget`, `DinouFromRoute`, `DinouRoutePattern`, `DinouLayoutPattern`, `DinouSlotPattern`, `DinouErrorPattern`, `DinouNotFoundPattern`, `DinouSegmentPattern`, `DinouRouter`, `CleanRoutePath`, `ExtractRouteParams`, `ExtractSegmentParam`, `LinkProps`, `ScopedLinkProps`, `ScopedLinkComponent`, `ScopedUseRouterHook`, `ClientRedirectProps`, `NavigationOptions`, `DinouEnv`, `RequestContextStore`, `ResponseProxy`, `CookieOptions`, `Query`, `Cookies`, `Headers`, `DinouConfig`, `DinouPlugin`, `ServerHookContext`, `NodeMiddleware` | TypeScript Types | Complete compile-time routing, segment prop, slot, relative navigation, context, env, and plugin types |
510
+
511
+ ### Contextual Virtual Module `"./dinou"` (Inside `src/` Route & `@slot` Folders, or `"../dinou"` from Nested `components/`)
512
+ | Export | Kind | Description |
513
+ | :--- | :--- | :--- |
514
+ | `ROUTE` | Constant (`string`) | Exact URL route pattern of that folder (e.g. `"/blog/[slug]"`) |
515
+ | `Link`, `useRouter` | Component / Hook | Pre-bound to `from={ROUTE}` so relative paths (`"sub"`, `"./sub"`, `"../other"`) validate & resolve without `from` |
516
+ | `PageProps<TProps?>`, `LayoutProps<TProps?>`, `SlotProps`, `ErrorProps`, `NotFoundProps<TProps?>`, `PageFunctions<TProps?>`, `LayoutFunctions<TProps?>`, `RouteParams<T?>`, `LinkProps` | TypeScript Types | Zero-boilerplate segment & link contracts pre-bound to that folder (`LayoutProps` auto-infers sibling `@slot` props) |
517
+ | All other `"dinou"` values & types | Re-exports | Full parity with `"dinou"` (`defineConfig`, `getContext`, `noDynamic`, hooks, `redirect`, `ClientRedirect`, types including `DinouEnv`) |
493
518
 
494
519
  ### Package `"dinou/server"`
495
520
  | Export | Kind | Description |
@@ -498,20 +523,20 @@ Running `npx dinou eject` copies the complete Dinou framework into `./dinou` at
498
523
  | `getContext` | Function (Server) | Returns `{ req, res, env, ctx, ...custom }` from `AsyncLocalStorage` (also in `"dinou"`) |
499
524
  | `noDynamic` | Function (Server) | Opts enclosing `<Suspense>` out of becoming a Dynamic PPR Hole (also in `"dinou"`) |
500
525
  | `revalidateTag` | Function (Server) | `await revalidateTag(tag)` — invalidates tagged pages, layouts & slots |
501
- | `revalidatePath` | Function (Server) | `await revalidatePath(path)` — invalidates route layout + page |
526
+ | `revalidatePath` | Function (Server) | `await revalidatePath(path)` — invalidates route layout + page (supports relative paths in Server Functions) |
502
527
  | `revalidatePage` | Function (Server) | `await revalidatePage(path)` — invalidates only `page.rsc` + `index.html` |
503
528
  | `revalidateLayout` | Function (Server) | `await revalidateLayout(path)` — invalidates only `layout.rsc` (lazy HTML re-composition) |
504
529
  | `StorageAdapter`, `FileSystemStorage`, `CloudflareKVStorage`, `DenoKVStorage`, `MemoryStorage`, `RedisStorage`, `getStorageAdapter`, `setStorageAdapter` | Storage API | Pluggable cache storage engines for SSG / ISR / PPR / `DinouCacheSlot` |
505
- | `DinouCacheSlotProps`, `StorageItem`, plus all server/route/page/layout/context/plugin types (`PageProps<T>`, `LayoutProps<T>`, `ErrorProps<T>`, `PageFunctions<T, P>`, `LayoutFunctions<T, P>`, `RouteSegmentConfig`, `PPRConfig`, `StaticPathItem`, `StaticPathsResult`, `RouteParams<T>`, `DinouRoute`, `DinouRoutePattern`, `DinouRouter`, `CleanRoutePath`, `ExtractRouteParams`, `ExtractSegmentParam`, `RequestContextStore`, `ResponseProxy`, `CookieOptions`, `Query`, `Cookies`, `Headers`, `DinouConfig`, `DinouPlugin`, `ServerHookContext`, `NodeMiddleware`) | TypeScript Types | Server-side & routing TypeScript definitions re-exported from `"dinou/server"` |
530
+ | `DinouCacheSlotProps`, `StorageItem`, `MemoryStorageOptions`, `RedisStorageOptions`, plus all routing, segment, slot, context & plugin types from `"dinou"` | TypeScript Types | Complete server-side & routing TypeScript definitions re-exported from `"dinou/server"` |
506
531
 
507
532
  ### Package `"dinou/config"` & Additional Subpaths
508
533
  | Subpath | Export / Purpose | Description |
509
534
  | :--- | :--- | :--- |
510
- | `"dinou/config"` | `defineConfig` (+ types from `index.d.ts`) | Dedicated config-only entry point (`dinou/core/config.js`) for `dinou.config.{mjs,js,ts}` |
511
- | `"dinou/env"` | Ambient TypeScript definitions | `/// <reference types="dinou/env" />` — declares module types for 21+ static asset & media extensions |
535
+ | `"dinou/config"` | `defineConfig`, `getContext`, `noDynamic` (+ types from `index.d.ts`) | Dedicated config entry point (`dinou/core/config.js`) for `dinou.config.{ts,mjs,js,cjs}` |
536
+ | `"dinou/env"` | Ambient TypeScript definitions | `/// <reference types="dinou/env" />` — declares module types for all 26 built-in static asset & media extensions |
512
537
  | `"dinou/adapters/{node,bun,deno,cloudflare,netlify}"` | Platform runtime adapters | Server entry points for each deployment runtime |
513
538
 
514
- > **Import Safety Rule:** `import { ... } from "dinou"` (and `import type`) is 100% safe in both Server Components/Functions and Client Components (`"use client"`). Runtime value imports `import { ... } from "dinou/server"` are **Server-Only** (pulling `node:*` modules), whereas `import type { ... } from "dinou/server"` is erased at compile time and safe anywhere.
539
+ > **Import Safety:** `"dinou"`, contextual `"./dinou"`, and any `import type` are safe in both Server and `"use client"` modules. Runtime value imports from `"dinou/server"` are **Server-Only** (`node:*`).
515
540
 
516
541
  ---
517
542