npm - @rangojs/router - Versions diffs - 0.0.0-experimental.97 → 0.0.0-experimental.98914650 - Mend

@rangojs/router 0.0.0-experimental.97 → 0.0.0-experimental.98914650

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 (356) hide show

package/README.md +24 -9
package/dist/bin/rango.js +157 -63
package/dist/testing/vitest.js +82 -0
package/dist/vite/index.js +1584 -639
package/package.json +71 -21
package/skills/api-client/SKILL.md +211 -0
package/skills/breadcrumbs/SKILL.md +60 -0
package/skills/bundle-analysis/SKILL.md +159 -0
package/skills/cache-guide/SKILL.md +222 -30
package/skills/caching/SKILL.md +263 -8
package/skills/composability/SKILL.md +27 -2
package/skills/css/SKILL.md +76 -0
package/skills/document-cache/SKILL.md +78 -55
package/skills/handler-use/SKILL.md +3 -1
package/skills/hooks/SKILL.md +235 -28
package/skills/host-router/SKILL.md +122 -22
package/skills/i18n/SKILL.md +276 -0
package/skills/intercept/SKILL.md +29 -5
package/skills/layout/SKILL.md +13 -9
package/skills/links/SKILL.md +173 -17
package/skills/loader/SKILL.md +170 -23
package/skills/middleware/SKILL.md +16 -10
package/skills/migrate-nextjs/SKILL.md +38 -16
package/skills/mime-routes/SKILL.md +27 -0
package/skills/observability/SKILL.md +137 -0
package/skills/parallel/SKILL.md +11 -7
package/skills/prerender/SKILL.md +14 -33
package/skills/rango/SKILL.md +250 -25
package/skills/react-compiler/SKILL.md +168 -0
package/skills/response-routes/SKILL.md +114 -47
package/skills/route/SKILL.md +42 -5
package/skills/router-setup/SKILL.md +3 -3
package/skills/server-actions/SKILL.md +78 -42
package/skills/tailwind/SKILL.md +27 -3
package/skills/testing/SKILL.md +129 -0
package/skills/testing/bindings.md +89 -0
package/skills/testing/cache-prerender.md +124 -0
package/skills/testing/client-components.md +122 -0
package/skills/testing/e2e-parity.md +125 -0
package/skills/testing/flight.md +92 -0
package/skills/testing/handles.md +129 -0
package/skills/testing/loader.md +128 -0
package/skills/testing/middleware.md +99 -0
package/skills/testing/render-handler.md +121 -0
package/skills/testing/response-routes.md +95 -0
package/skills/testing/reverse-and-types.md +84 -0
package/skills/testing/server-actions.md +107 -0
package/skills/testing/server-tree.md +128 -0
package/skills/testing/setup.md +120 -0
package/skills/typesafety/SKILL.md +316 -26
package/skills/use-cache/SKILL.md +36 -5
package/skills/vercel/SKILL.md +107 -0
package/skills/view-transitions/SKILL.md +294 -0
package/src/__augment-tests__/augment.ts +81 -0
package/src/__augment-tests__/augmented.check.ts +116 -0
package/src/__internal.ts +0 -65
package/src/browser/action-coordinator.ts +53 -36
package/src/browser/action-fence.ts +47 -0
package/src/browser/app-shell.ts +14 -27
package/src/browser/cookie-name.ts +140 -0
package/src/browser/event-controller.ts +37 -143
package/src/browser/history-state.ts +21 -0
package/src/browser/index.ts +3 -3
package/src/browser/invalidate-client-cache.ts +52 -0
package/src/browser/navigation-bridge.ts +30 -59
package/src/browser/navigation-client.ts +96 -84
package/src/browser/navigation-store-handle.ts +38 -0
package/src/browser/navigation-store.ts +32 -82
package/src/browser/navigation-transaction.ts +9 -59
package/src/browser/partial-update.ts +60 -127
package/src/browser/prefetch/cache.ts +82 -72
package/src/browser/prefetch/fetch.ts +108 -33
package/src/browser/prefetch/queue.ts +6 -3
package/src/browser/rango-state.ts +157 -115
package/src/browser/react/Link.tsx +0 -2
package/src/browser/react/NavigationProvider.tsx +41 -48
package/src/browser/react/ScrollRestoration.tsx +10 -6
package/src/browser/react/filter-segment-order.ts +0 -2
package/src/browser/react/index.ts +0 -48
package/src/browser/react/location-state-shared.ts +166 -8
package/src/browser/react/location-state.ts +39 -14
package/src/browser/react/use-action.ts +6 -15
package/src/browser/react/use-handle.ts +17 -14
package/src/browser/react/use-link-status.ts +0 -4
package/src/browser/react/use-navigation.ts +0 -3
package/src/browser/react/use-params.ts +11 -11
package/src/browser/react/use-reverse.ts +106 -0
package/src/browser/react/use-router.ts +20 -5
package/src/browser/react/use-search-params.ts +0 -5
package/src/browser/react/use-segments.ts +0 -13
package/src/browser/response-adapter.ts +52 -1
package/src/browser/rsc-router.tsx +70 -34
package/src/browser/scroll-restoration.ts +22 -14
package/src/browser/segment-structure-assert.ts +2 -2
package/src/browser/server-action-bridge.ts +168 -44
package/src/browser/types.ts +36 -21
package/src/browser/validate-redirect-origin.ts +43 -16
package/src/build/collect-fallback-refs.ts +107 -0
package/src/build/generate-manifest.ts +60 -35
package/src/build/generate-route-types.ts +3 -0
package/src/build/index.ts +8 -2
package/src/build/prefix-tree-utils.ts +123 -0
package/src/build/route-trie.ts +89 -10
package/src/build/route-types/codegen.ts +4 -4
package/src/build/route-types/include-resolution.ts +1 -1
package/src/build/route-types/param-extraction.ts +6 -3
package/src/build/route-types/per-module-writer.ts +7 -4
package/src/build/route-types/router-processing.ts +122 -22
package/src/build/route-types/scan-filter.ts +1 -1
package/src/build/route-types/source-scan.ts +118 -0
package/src/build/runtime-discovery.ts +9 -20
package/src/cache/cache-error.ts +104 -0
package/src/cache/cache-policy.ts +68 -28
package/src/cache/cache-runtime.ts +134 -32
package/src/cache/cache-scope.ts +100 -74
package/src/cache/cache-tag.ts +98 -0
package/src/cache/cf/cf-cache-store.ts +2255 -238
package/src/cache/cf/index.ts +6 -16
package/src/cache/document-cache.ts +61 -20
package/src/cache/handle-snapshot.ts +63 -0
package/src/cache/index.ts +22 -20
package/src/cache/memory-segment-store.ts +136 -37
package/src/cache/profile-registry.ts +6 -30
package/src/cache/read-through-swr.ts +41 -11
package/src/cache/segment-codec.ts +0 -16
package/src/cache/tag-invalidation.ts +230 -0
package/src/cache/types.ts +33 -100
package/src/cache/vercel/index.ts +11 -0
package/src/cache/vercel/vercel-cache-store.ts +799 -0
package/src/client.rsc.tsx +6 -21
package/src/client.tsx +25 -61
package/src/component-utils.ts +19 -0
package/src/context-var.ts +17 -5
package/src/decode-loader-results.ts +36 -0
package/src/defer.ts +196 -0
package/src/deps/ssr.ts +0 -1
package/src/errors.ts +30 -4
package/src/handle.ts +31 -23
package/src/handles/MetaTags.tsx +0 -14
package/src/handles/breadcrumbs.ts +16 -5
package/src/handles/meta.ts +0 -39
package/src/host/cookie-handler.ts +0 -36
package/src/host/errors.ts +0 -24
package/src/host/index.ts +8 -2
package/src/host/pattern-matcher.ts +7 -50
package/src/host/router.ts +107 -99
package/src/host/testing.ts +40 -27
package/src/host/types.ts +37 -4
package/src/host/utils.ts +1 -1
package/src/href-client.ts +137 -22
package/src/index.rsc.ts +63 -9
package/src/index.ts +64 -9
package/src/internal-debug.ts +2 -4
package/src/loader-store.ts +500 -0
package/src/loader.rsc.ts +20 -13
package/src/loader.ts +12 -11
package/src/missing-id-error.ts +68 -0
package/src/network-error-thrower.tsx +1 -6
package/src/outlet-provider.tsx +1 -5
package/src/prerender/param-hash.ts +10 -11
package/src/prerender/store.ts +32 -37
package/src/prerender.ts +61 -6
package/src/redirect-origin.ts +100 -0
package/src/response-utils.ts +9 -0
package/src/reverse.ts +65 -40
package/src/root-error-boundary.tsx +1 -19
package/src/route-content-wrapper.tsx +7 -72
package/src/route-definition/dsl-helpers.ts +244 -281
package/src/route-definition/helper-factories.ts +29 -139
package/src/route-definition/helpers-types.ts +40 -17
package/src/route-definition/redirect.ts +43 -9
package/src/route-definition/resolve-handler-use.ts +6 -0
package/src/route-definition/use-item-types.ts +32 -0
package/src/route-map-builder.ts +0 -16
package/src/route-types.ts +19 -41
package/src/router/basename.ts +14 -0
package/src/router/content-negotiation.ts +15 -15
package/src/router/error-handling.ts +13 -17
package/src/router/find-match.ts +44 -23
package/src/router/handler-context.ts +4 -41
package/src/router/intercept-resolution.ts +14 -19
package/src/router/lazy-includes.ts +9 -46
package/src/router/loader-resolution.ts +91 -46
package/src/router/logging.ts +0 -6
package/src/router/manifest.ts +18 -29
package/src/router/match-api.ts +0 -20
package/src/router/match-context.ts +0 -22
package/src/router/match-handlers.ts +57 -58
package/src/router/match-middleware/background-revalidation.ts +0 -7
package/src/router/match-middleware/cache-lookup.ts +150 -271
package/src/router/match-middleware/cache-store.ts +3 -33
package/src/router/match-middleware/intercept-resolution.ts +0 -22
package/src/router/match-middleware/segment-resolution.ts +0 -22
package/src/router/match-pipelines.ts +1 -42
package/src/router/match-result.ts +31 -80
package/src/router/metrics.ts +0 -34
package/src/router/middleware-types.ts +5 -112
package/src/router/middleware.ts +118 -133
package/src/router/navigation-snapshot.ts +0 -51
package/src/router/params-util.ts +23 -0
package/src/router/pattern-matching.ts +62 -67
package/src/router/prerender-match.ts +99 -63
package/src/router/preview-match.ts +3 -1
package/src/router/request-classification.ts +28 -62
package/src/router/revalidation.ts +50 -56
package/src/router/route-snapshot.ts +0 -1
package/src/router/router-context.ts +0 -27
package/src/router/router-interfaces.ts +68 -35
package/src/router/router-options.ts +55 -1
package/src/router/router-registry.ts +2 -5
package/src/router/segment-resolution/fresh.ts +44 -63
package/src/router/segment-resolution/helpers.ts +34 -0
package/src/router/segment-resolution/loader-cache.ts +40 -37
package/src/router/segment-resolution/revalidation.ts +203 -285
package/src/router/segment-resolution/static-store.ts +19 -5
package/src/router/segment-resolution/streamed-handler-telemetry.ts +52 -0
package/src/router/segment-resolution/view-transition-default.ts +36 -0
package/src/router/segment-resolution.ts +4 -1
package/src/router/segment-wrappers.ts +0 -3
package/src/router/state-cookie-name.ts +33 -0
package/src/router/substitute-pattern-params.ts +56 -0
package/src/router/telemetry-otel.ts +0 -20
package/src/router/telemetry.ts +96 -19
package/src/router/timeout.ts +0 -20
package/src/router/trie-matching.ts +87 -48
package/src/router/types.ts +9 -63
package/src/router/url-params.ts +0 -5
package/src/router.ts +80 -41
package/src/rsc/handler-context.ts +3 -2
package/src/rsc/handler.ts +83 -78
package/src/rsc/helpers.ts +93 -5
package/src/rsc/index.ts +1 -1
package/src/rsc/json-route-result.ts +38 -0
package/src/rsc/manifest-init.ts +28 -41
package/src/rsc/origin-guard.ts +39 -25
package/src/rsc/progressive-enhancement.ts +12 -1
package/src/rsc/redirect-guard.ts +99 -0
package/src/rsc/response-error.ts +79 -12
package/src/rsc/response-route-handler.ts +76 -62
package/src/rsc/rsc-rendering.ts +41 -60
package/src/rsc/runtime-warnings.ts +23 -10
package/src/rsc/server-action.ts +62 -67
package/src/rsc/ssr-setup.ts +16 -0
package/src/rsc/types.ts +10 -5
package/src/runtime-env.ts +18 -0
package/src/search-params.ts +4 -20
package/src/segment-loader-promise.ts +14 -2
package/src/segment-system.tsx +199 -142
package/src/serialize.ts +243 -0
package/src/server/context.ts +150 -51
package/src/server/cookie-store.ts +80 -5
package/src/server/handle-store.ts +7 -24
package/src/server/loader-registry.ts +5 -24
package/src/server/request-context.ts +165 -87
package/src/ssr/index.tsx +14 -14
package/src/static-handler.ts +10 -13
package/src/testing/cache-status.ts +162 -0
package/src/testing/collect-handle.ts +40 -0
package/src/testing/dispatch.ts +618 -0
package/src/testing/dom.entry.ts +22 -0
package/src/testing/e2e/fixture.ts +188 -0
package/src/testing/e2e/index.ts +128 -0
package/src/testing/e2e/matchers.ts +35 -0
package/src/testing/e2e/page-helpers.ts +272 -0
package/src/testing/e2e/parity.ts +387 -0
package/src/testing/e2e/server.ts +195 -0
package/src/testing/flight-matchers.ts +97 -0
package/src/testing/flight-normalize.ts +11 -0
package/src/testing/flight-runtime.d.ts +57 -0
package/src/testing/flight-tree.ts +682 -0
package/src/testing/flight.entry.ts +52 -0
package/src/testing/flight.ts +232 -0
package/src/testing/generated-routes.ts +183 -0
package/src/testing/index.ts +99 -0
package/src/testing/internal/context.ts +348 -0
package/src/testing/internal/flight-client-globals.ts +30 -0
package/src/testing/internal/seed-vars.ts +54 -0
package/src/testing/render-handler.ts +330 -0
package/src/testing/render-route.tsx +566 -0
package/src/testing/run-loader.ts +378 -0
package/src/testing/run-middleware.ts +205 -0
package/src/testing/vitest-stubs/cloudflare-email.ts +9 -0
package/src/testing/vitest-stubs/cloudflare-workers.ts +21 -0
package/src/testing/vitest-stubs/plugin-rsc.ts +16 -0
package/src/testing/vitest-stubs/version.ts +5 -0
package/src/testing/vitest.ts +305 -0
package/src/theme/ThemeProvider.tsx +0 -52
package/src/theme/ThemeScript.tsx +0 -6
package/src/theme/constants.ts +0 -12
package/src/theme/index.ts +0 -7
package/src/theme/theme-context.ts +1 -5
package/src/theme/theme-script.ts +0 -14
package/src/theme/use-theme.ts +0 -3
package/src/types/boundaries.ts +0 -35
package/src/types/cache-types.ts +13 -4
package/src/types/error-types.ts +30 -90
package/src/types/global-namespace.ts +54 -41
package/src/types/handler-context.ts +97 -22
package/src/types/index.ts +1 -10
package/src/types/loader-types.ts +6 -3
package/src/types/request-scope.ts +0 -19
package/src/types/route-config.ts +6 -50
package/src/types/route-entry.ts +0 -6
package/src/types/segments.ts +18 -14
package/src/urls/include-helper.ts +9 -56
package/src/urls/index.ts +1 -11
package/src/urls/path-helper-types.ts +19 -5
package/src/urls/path-helper.ts +17 -106
package/src/urls/pattern-types.ts +36 -19
package/src/urls/response-types.ts +20 -19
package/src/urls/type-extraction.ts +58 -139
package/src/urls/urls-function.ts +1 -18
package/src/use-loader.tsx +292 -107
package/src/vite/debug.ts +1 -0
package/src/vite/discovery/bundle-postprocess.ts +8 -7
package/src/vite/discovery/discover-routers.ts +95 -82
package/src/vite/discovery/discovery-errors.ts +194 -0
package/src/vite/discovery/prerender-collection.ts +26 -34
package/src/vite/discovery/route-types-writer.ts +40 -84
package/src/vite/discovery/state.ts +39 -1
package/src/vite/discovery/virtual-module-codegen.ts +14 -34
package/src/vite/index.ts +4 -0
package/src/vite/plugin-types.ts +185 -10
package/src/vite/plugins/cjs-to-esm.ts +3 -18
package/src/vite/plugins/client-ref-dedup.ts +0 -11
package/src/vite/plugins/client-ref-hashing.ts +12 -11
package/src/vite/plugins/cloudflare-protocol-stub.ts +1 -21
package/src/vite/plugins/expose-action-id.ts +4 -75
package/src/vite/plugins/expose-id-utils.ts +3 -54
package/src/vite/plugins/expose-ids/export-analysis.ts +76 -34
package/src/vite/plugins/expose-ids/handler-transform.ts +6 -74
package/src/vite/plugins/expose-ids/loader-transform.ts +3 -20
package/src/vite/plugins/expose-ids/router-transform.ts +0 -13
package/src/vite/plugins/expose-internal-ids.ts +57 -67
package/src/vite/plugins/performance-tracks.ts +9 -16
package/src/vite/plugins/refresh-cmd.ts +1 -1
package/src/vite/plugins/use-cache-transform.ts +26 -49
package/src/vite/plugins/vercel-output.ts +258 -0
package/src/vite/plugins/version-injector.ts +2 -32
package/src/vite/plugins/version-plugin.ts +32 -23
package/src/vite/plugins/virtual-entries.ts +35 -17
package/src/vite/rango.ts +148 -115
package/src/vite/router-discovery.ts +220 -68
package/src/vite/utils/ast-handler-extract.ts +15 -31
package/src/vite/utils/bundle-analysis.ts +10 -15
package/src/vite/utils/client-chunks.ts +184 -0
package/src/vite/utils/forward-user-plugins.ts +171 -0
package/src/vite/utils/manifest-utils.ts +4 -59
package/src/vite/utils/package-resolution.ts +1 -73
package/src/vite/utils/prerender-utils.ts +0 -34
package/src/vite/utils/shared-utils.ts +95 -43
package/src/browser/action-response-classifier.ts +0 -99
package/src/browser/react/use-client-cache.ts +0 -58
package/src/browser/shallow.ts +0 -40
package/src/handles/index.ts +0 -7
package/src/router/middleware-cookies.ts +0 -55

package/skills/css/SKILL.md ADDED Viewed

@@ -0,0 +1,76 @@
+---
+name: css
+description: Import and apply CSS in a Rango app. Render document/app stylesheets in the Document `<head>` with Vite's `?url` import plus a `precedence`-managed `<link rel="stylesheet">` (React 19 resource model — deduped, ordered, loaded before paint). Use when wiring global/app CSS or a Document `<head>` stylesheet, or when deciding between `?url` + `<link>` and side-effect imports. Cross-app (host-router) navigation is a full document load, so each app's document CSS is always re-established by its own load.
+argument-hint:
+---
+# CSS imports
+Document/app CSS in Rango lives in the Document `<head>`, loaded with Vite's
+`?url` import and a `precedence`-managed `<link rel="stylesheet">`. This page is
+the why and the one cross-app caveat; `/tailwind` is the concrete setup, `/theme`
+is dark mode, `/fonts` is fonts.
+## The pattern
+```tsx
+// document.tsx
+"use client";
+import type { ReactNode } from "react";
+import { MetaTags } from "@rangojs/router/client";
+import styles from "./index.css?url";
+export function Document({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <link rel="preload" href={styles} as="style" precedence="default" />
+        <link rel="stylesheet" href={styles} precedence="default" />
+        <MetaTags />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+- **`?url`** returns the processed file's hashed URL instead of injecting it as a
+  side effect, giving a stable asset path that works in dev and production.
+- **`precedence`** opts the `<link rel="stylesheet">` into React 19's managed
+  stylesheet model: React de-duplicates it by `href`, orders it by precedence
+  (any string value — it only decides cascade order relative to other managed
+  sheets), and loads it **before paint**, so there is no flash of unstyled
+  content. This is the recommended way to render a stylesheet link.
+## Cross-app (host-router) navigation
+You do **not** need to coordinate CSS across apps mounted under one host router.
+A client-side navigation that crosses an app boundary is a **full document load**
+(the server returns `X-RSC-Reload` on an app switch — see `/host-router`), so the
+target app's entire document — its stylesheets, theme, meta — is re-established
+by the target app's own load. Each app owns its document; how one app renders a
+stylesheet has no effect on another.
+(This replaced an earlier soft cross-app swap. Under it, a stylesheet shared
+across apps by `href` — classically every app's `@import "tailwindcss"` compiling
+to one hashed asset — could be silently dropped by React's by-`href` resource
+dedup when the apps disagreed on `precedence` (one unmanaged, one managed). The
+full reload removes that footgun entirely, which is the main reason cross-app
+navigation is a hard boundary.)
+## Side-effect imports vs `?url`
+A bare `import "./index.css"` (no `?url`, no `<link>`) also produces _managed_ CSS
+— `@vitejs/plugin-rsc` collects it via `import.meta.viteRsc.loadCss` and injects
+it with a precedence. It is fine for **component-local** CSS that loads with its
+client chunk. For **document-level** CSS, prefer the `?url` + `<link precedence>`
+form above: a side-effect import is not guaranteed to be in the initial streamed
+`<head>` (an SSR-streaming caveat), whereas the explicit `<link>` is.
+## Related
+- `/tailwind` — Tailwind v4 setup using this pattern.
+- `/host-router` — multi-app routing; why cross-app navigation is a full reload.
+- `/theme` — dark mode / theme attribute.
+- `/fonts` — self-hosted fonts via `@fontsource`.

package/skills/document-cache/SKILL.md CHANGED Viewed

@@ -10,73 +10,82 @@ Caches complete HTTP responses (HTML/RSC) at the edge based on Cache-Control hea
 ## Setup
-Configure document cache in router:
+Document caching is a middleware. Add `createDocumentCacheMiddleware()` to the
+router with `.use()`. The cache store it reads from is the app-level store you
+configure on `createRouter({ cache })` (available on the request context as
+`requestCtx._cacheStore`), not a store passed to the middleware.
 ```typescript
 import { createRouter } from "@rangojs/router";
-import { CFCacheStore } from "@rangojs/router/cache";
+import {
+  createDocumentCacheMiddleware,
+  CFCacheStore,
+} from "@rangojs/router/cache";
 import { urlpatterns } from "./urls";
 const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
-  documentCache: (_env, ctx) => ({
-    store: new CFCacheStore({ ctx: ctx! }),
+  // App-level cache store. The document cache middleware uses this store's
+  // getResponse/putResponse methods.
+  cache: (_env, ctx) => new CFCacheStore({ ctx: ctx! }),
+});
+router.use(
+  createDocumentCacheMiddleware({
     skipPaths: ["/api", "/admin"],
     debug: process.env.NODE_ENV === "development",
   }),
-});
+);
 export default router;
 ```
-## Route Opt-In with cache()
+## Route Opt-In with Cache-Control
-Routes opt-in to document caching using the `cache()` DSL with `documentCache` option:
+Routes opt-in to document caching by setting a `Cache-Control` response header
+with `s-maxage`. The middleware caches responses whose `Cache-Control` includes
+`s-maxage`; `stale-while-revalidate` enables background revalidation (SWR).
 ```typescript
-import { urls } from "@rangojs/router";
-export const urlpatterns = urls(({ path, cache }) => [
-  // Cache full page for 5 min, serve stale for 1 hour
-  cache({ documentCache: { sMaxAge: 300, swr: 3600 } }, () => [
-    path("/blog", BlogIndex, { name: "blog" }),
-  ]),
-  // Long cache for individual posts
-  cache({ documentCache: { sMaxAge: 3600, swr: 86400 } }, () => [
-    path("/blog/:slug", BlogPost, { name: "blogPost" }),
-  ]),
-  // No cache for dashboard (no documentCache option)
-  path("/dashboard", Dashboard, { name: "dashboard" }),
-]);
+// Cache full page for 5 min, serve stale for 1 hour
+function BlogIndexHandler(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+  return <BlogIndex />;
+}
+// Long cache for individual posts
+function BlogPostHandler(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=3600, stale-while-revalidate=86400");
+  return <BlogPost />;
+}
+// Dashboard sets no Cache-Control header, so it is never document-cached.
 ```
 ## Document Cache Options
-```typescript
-createRouter({
-  // ...
-  documentCache: (_env, ctx) => ({
-    // Cache store (required)
-    store: new CFCacheStore({ ctx: ctx! }),
+`createDocumentCacheMiddleware(options?)` accepts:
-    // Skip specific paths
-    skipPaths: ["/api", "/admin"],
+```typescript
+createDocumentCacheMiddleware({
+  // Skip specific paths (matched by pathname prefix)
+  skipPaths: ["/api", "/admin"],
-    // Custom cache key
-    keyGenerator: (url) => url.pathname,
+  // Custom cache key generator
+  keyGenerator: (url) => url.pathname,
-    // Conditional caching
-    isEnabled: (ctx) => !ctx.request.headers.has("x-preview"),
+  // Conditional caching, evaluated per request
+  isEnabled: (ctx) => !ctx.request.headers.has("x-preview"),
-    // Debug logging
-    debug: true,
-  }),
+  // Debug logging (HIT, MISS, STALE, REVALIDATED)
+  debug: true,
 });
 ```
+The cache store is not a middleware option — it comes from the app-level
+`createRouter({ cache })` store.
 ## How It Works
 ```
@@ -89,7 +98,7 @@ Request → Check Cache
     ↓             ↓
   Fresh?      Run handler
     │             │
-   Yes → Return   Has documentCache?
+   Yes → Return   Has s-maxage?
     │             │
    No (stale)    Yes → Cache + Return
     │             │
@@ -120,13 +129,14 @@ Segment hash ensures different cached responses for navigations from different s
 - Full HTML responses (document requests)
 - RSC payloads (client navigation)
-- Only 200 OK responses with documentCache enabled
+- Only 200 OK responses whose `Cache-Control` includes `s-maxage`
 ## What's NOT Cached
 - Server actions (`_rsc_action`)
 - Loader requests (`_rsc_loader`)
-- Routes without `documentCache` option
+- Non-GET requests
+- Responses without an `s-maxage` `Cache-Control` directive
 - Non-200 responses
 ## Complete Example
@@ -134,40 +144,53 @@ Segment hash ensures different cached responses for navigations from different s
 ```typescript
 // router.tsx
 import { createRouter } from "@rangojs/router";
-import { CFCacheStore } from "@rangojs/router/cache";
+import { createDocumentCacheMiddleware, CFCacheStore } from "@rangojs/router/cache";
 import { urlpatterns } from "./urls";
 const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
-  documentCache: (_env, ctx) => ({
-    store: new CFCacheStore({ ctx: ctx! }),
+  cache: (_env, ctx) => new CFCacheStore({ ctx: ctx! }),
+});
+router.use(
+  createDocumentCacheMiddleware({
     skipPaths: ["/api"],
     debug: process.env.NODE_ENV === "development",
   }),
-});
+);
 export default router;
 // urls.tsx
 import { urls } from "@rangojs/router";
-export const urlpatterns = urls(({ path, layout, cache, loader }) => [
-  // Blog with document caching
-  cache({ documentCache: { sMaxAge: 300, swr: 3600 } }, () => [
-    layout(<BlogLayout />, () => [
-      path("/blog", BlogIndex, { name: "blog" }),
-      path("/blog/:slug", BlogPost, { name: "blogPost" }, () => [
-        loader(BlogPostLoader),
-      ]),
+export const urlpatterns = urls(({ path, layout, loader }) => [
+  // Blog pages opt into document caching via Cache-Control headers set in
+  // their handlers (see BlogIndex / BlogPost below).
+  layout(<BlogLayout />, () => [
+    path("/blog", BlogIndex, { name: "blog" }),
+    path("/blog/:slug", BlogPost, { name: "blogPost" }, () => [
+      loader(BlogPostLoader),
     ]),
   ]),
-  // Dashboard - no document cache (dynamic content)
+  // Dashboard sets no Cache-Control header, so it is never document-cached.
   layout(<DashboardLayout />, () => [
     path("/dashboard", Dashboard, { name: "dashboard" }),
   ]),
 ]);
+// Blog handlers set s-maxage to opt into the document cache.
+function BlogIndex(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+  return <BlogIndexPage />;
+}
+function BlogPost(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+  return <BlogPostPage />;
+}
 ```
 ## Document Cache vs Segment Cache
@@ -175,7 +198,7 @@ export const urlpatterns = urls(({ path, layout, cache, loader }) => [
 | Feature      | Document Cache             | Segment Cache         |
 | ------------ | -------------------------- | --------------------- |
 | Granularity  | Full response              | Individual segments   |
-| Opt-in       | `documentCache` in cache() | `cache({ ttl, swr })` |
+| Opt-in       | `Cache-Control` `s-maxage` | `cache({ ttl, swr })` |
 | Use case     | Static pages               | Dynamic compositions  |
 | Key includes | URL + segment hash         | Route params          |

package/skills/handler-use/SKILL.md CHANGED Viewed

@@ -59,6 +59,8 @@ Now `ProductPage` carries its loader, loading state, and response-header middlew
 | `intercept()`                                     | `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `layout`, `route`, `when`, `transition`                  |
 | Response routes (`path.json()`, `path.text()`, …) | `middleware`, `cache`                                                                                                                          |
+For per-item semantics see the dedicated skills: [middleware](../middleware/SKILL.md), [loader](../loader/SKILL.md), [parallel](../parallel/SKILL.md), [intercept](../intercept/SKILL.md), [layout](../layout/SKILL.md), [view-transitions](../view-transitions/SKILL.md).
 If `handler.use()` returns a disallowed item for a mount site, registration throws:
 ```
@@ -295,7 +297,7 @@ QuickViewModal.use = () => [
 ## `loading()` is a single-assignment item — scope it correctly
-Most `use` items accumulate when merged: `handler.use` `middleware()` runs _and_ explicit `middleware()` runs; both `loader()` registrations apply. `loading()` is different — it mutates `entry.loading` directly, last call wins ([dsl-helpers.ts `loadingFn`](../../src/route-definition/dsl-helpers.ts)).
+Most `use` items accumulate when merged: `handler.use` `middleware()` runs _and_ explicit `middleware()` runs; both `loader()` registrations apply. `loading()` is different — it mutates `entry.loading` directly, last call wins ([dsl-helpers.ts `loading`](../../src/route-definition/dsl-helpers.ts)).
 For pages, layouts, and intercepts that's straightforward: explicit `loading()` at the mount site replaces any `loading()` from `handler.use`. The merge order is `handler.use → explicit`, so the explicit one is the last writer and wins.

package/skills/hooks/SKILL.md CHANGED Viewed

@@ -89,8 +89,8 @@ import { useSegments } from "@rangojs/router/client";
 function Breadcrumbs() {
   const { path, segmentIds, location } = useSegments();
-  // path: ["/shop", "products", "123"]
-  // segmentIds: ["shop-layout", "products-route"]
+  // path: ["shop", "products", "123"] (split on "/", no leading slash on any element)
+  // segmentIds: ["L0", "L0L1", "L0L1R0"] (opaque internal short-codes, not route names)
   // location: URL object
   return <nav>{path.join(" > ")}</nav>;
@@ -190,6 +190,141 @@ function SearchResults() {
 }
 ```
+**Shared refetch behavior**:
+When the loader is registered on the route via `loader()`, a plain
+`load()` call (no options, or a trivially-defaulted GET with no
+`params` and no `body`) broadcasts its result to every component
+reading the same loader id. Layout, page, and parallel-slot reads
+all converge on the new value:
+```tsx
+// Layout button calls load() — the page read below sees the update too.
+function Layout() {
+  const { data, load } = useLoader(CartLoader);
+  return <button onClick={() => load()}>Refresh ({data.count})</button>;
+}
+function Page() {
+  const { data } = useLoader(CartLoader); // updates with the layout's load()
+  return <span>{data.count} items</span>;
+}
+```
+`isLoading` and `error` follow the same scope. `throwOnError: true`
+render-throws are scoped to the **originating** hook — sibling readers
+see the error in their `error` state but their boundaries are not
+triggered by someone else's failure. A successful follow-up `load()`
+clears the shared error.
+**`load()` calls that stay local** (no broadcast, per-hook state, same
+semantics as the old per-component `useState`):
+- `load({ params: { ... } })` — explicit params.
+- `load({ method: "POST", body })` — mutations.
+- Any `load()` on a `useFetchLoader(loader)` whose loader is **not**
+  registered on the current route. Two unrelated components calling
+  `load()` on the same fetchable-but-unregistered loader keep
+  independent results.
+So the search/list pattern still works — two components calling
+`load({ params: { q } })` with different `q` values each keep their
+own result; they do not collapse to last-write-wins through a shared
+store.
+**Scoping refetch with a `key`**:
+Pass a `key` to partition the shared refresh store. Only hooks using the
+**same** `key` refresh together when one of them calls `load()`. This is a
+client-side refresh identity only — it never changes the request sent to the
+server, and is unrelated to the server `cache({ key })` option and to
+`revalidate()`.
+```tsx
+// Two independent dashboards using the same loader. Without a key, one
+// dashboard's load() would flip the other's spinner and value. With a key,
+// they refresh independently.
+function Dashboard({ id }: { id: string }) {
+  const { data, load } = useLoader(StatsLoader, { key: `dashboard:${id}` });
+  return <button onClick={() => load()}>Refresh {data.total}</button>;
+}
+```
+The `key` widens sharing in two ways the default cannot:
+- **Parameterized GETs share.** `useFetchLoader(SearchLoader, { key: q })`
+  with the same `q` in two components share one result and refresh together —
+  a keyed `load({ params: { q } })` broadcasts to the group instead of staying
+  local. (Mutations — non-GET or `body` — stay local even with a key.)
+- **Unregistered loaders share.** A `key` makes `useFetchLoader` of a loader
+  that is **not** registered on the route share too, letting unrelated
+  components opt into a common refresh group.
+Lifecycle: a keyed read of an unregistered loader is reference-counted — its
+shared value lives as long as at least one component using that key is mounted.
+A persistent component (e.g. a header) keeps the value across navigations; a
+route-scoped component's value is reclaimed when it unmounts. Registered-loader
+reads (keyed or not) reset on navigation from fresh route data, as before.
+**Refreshing multiple loaders together (`refreshGroup` + `useRefreshLoaders`)**:
+`key` groups readers of one loader. To refresh **different** loaders together,
+tag them with a shared `refreshGroup` name and trigger them with
+`useRefreshLoaders()`. The hook takes no argument; you pass the group(s) to the
+function it returns, so one `useRefreshLoaders()` can refresh different groups
+depending on context. A read may carry **several** tags — pass an array — and is
+refreshed when **any** of its groups is refreshed:
+```tsx
+function Profile() {
+  const { data } = useLoader(ProfileLoader, {
+    key: userId,
+    refreshGroup: "account",
+  });
+  return <span>{data.name}</span>;
+}
+function Orders() {
+  // Tagged into two groups: refreshed by "account" (the whole set) or the
+  // finer "orders" tag.
+  const { data } = useLoader(OrdersLoader, {
+    key: userId,
+    refreshGroup: ["account", "orders"],
+  });
+  return <span>{data.count} orders</span>;
+}
+function RefreshButtons() {
+  const refresh = useRefreshLoaders();
+  return (
+    <>
+      <button onClick={() => refresh("account")}>Refresh account</button>
+      <button onClick={() => refresh("orders")}>Refresh orders only</button>
+      <button onClick={() => refresh(["account", "orders"])}>
+        Refresh both
+      </button>
+    </>
+  );
+}
+```
+`refresh(groups)` accepts one name or an array and re-runs every currently-mounted
+member tagged with **any** of them, with a **plain GET** against the current route
+URL — no params, no body, no mutation methods, because a group spans loaders with
+different shapes. A member that sits in two of the requested groups is fetched
+once (members are unioned and deduped by read). It returns a promise that resolves
+when all members settle and **rejects with an `AggregateError`** if any fail;
+group refresh never render-throws, so handle failures at the await site
+(`await refresh("account").catch(...)`). Each failing member also exposes its
+error via its own read's `error`.
+Multiple tags give you granular vs. whole-set refresh from one place: a coarse
+tag (`"account"`) covers everything, while a finer tag (`"orders"`) targets a
+subset. Sharing within a group is opt-in via `key`: members that share a `key`
+share one value (and one fetch); a grouped reader **without** a `key` gets its own
+private bucket, so a group refresh updates only that read and never leaks into
+unrelated unkeyed reads of the same loader. A bucket may belong to several groups
+at once (one read tagged with multiple names, or different reads tagging the same
+keyed bucket with different names). Keep parameterized loaders on the single-loader
+`key` — a plain-GET group refresh sends no params.
 **Load options**:
 ```tsx
@@ -511,33 +646,81 @@ const flash = FlashMessage.read();
 const product = ProductState.read();
 ```
-## Cache Hooks
+> **Hydration:** `.read()` returns `undefined` on the server but may return
+> a real value on the first client render (history state survives reload).
+> Do not call `.read()` directly during the initial render of a component;
+> call it from an event handler or inside a `useEffect` post-mount. For
+> reactive hydration-safe access, use `useLocationState()` instead.
+### .write() / .delete() (static, non-reactive)
-### useClientCache()
+Static counterparts to `.read()`. Both mutate the current history entry's
+`history.state` via `replaceState`, preserving any other keys (router
+bookkeeping, other location state slots). Both are client-only; they throw
+when called on the server.
-Manually control client-side navigation cache:
+Neither dispatches an event, so components reading via `useLocationState`
+will NOT re-render until the next navigation/popstate. Pair with `.read()`
+(or a fresh mount via back/forward/reload) instead.
 ```tsx
 "use client";
-import { useClientCache } from "@rangojs/router/client";
+import { ProductState } from "./state";
-function SaveButton() {
-  const { clear } = useClientCache();
+// Persisted across hard refresh and back/forward of this entry.
+ProductState.write({ name: "Widget", price: 9.99 });
+// Read later (or on next mount).
+const current = ProductState.read();
+// Manually clear the slot. Idempotent if it isn't set.
+ProductState.delete();
+```
+| Method      | Updates `history.state` | Fires `useLocationState` rerender | SSR behavior        |
+| ----------- | ----------------------- | --------------------------------- | ------------------- |
+| `.read()`   | no                      | n/a (returns snapshot)            | returns `undefined` |
+| `.write()`  | yes (replace this slot) | no                                | throws              |
+| `.delete()` | yes (remove this slot)  | no                                | throws              |
+## Cache Control
+### invalidateClientCache()
+Force the client's caches to miss after a mutation the router can't see (a REST
+call, a WebSocket push, a login). It is a plain function, not a hook, so it works
+from module-level callbacks too. Imported from the root entry `@rangojs/router`,
+it is selected by export conditions: in a client component it marks the caches
+stale immediately; from a handler/server component it writes a rotated
+`Set-Cookie` for the responding client.
+```tsx
+"use client";
+import { invalidateClientCache } from "@rangojs/router";
+function SaveButton() {
   const handleSave = async () => {
     await fetch("/api/data", {
       method: "POST",
       body: JSON.stringify(data),
     });
-    // Invalidate cache after mutation
-    clear();
+    // Invalidate the client's caches after the mutation
+    invalidateClientCache();
   };
   return <button onClick={handleSave}>Save</button>;
 }
 ```
+A module-level subscription works the same way (no component needed):
+```ts
+import { invalidateClientCache } from "@rangojs/router";
+socket.on("catalog-updated", () => invalidateClientCache());
+```
 **Use cases**: REST API mutations, WebSocket updates, non-RSC data changes.
 ## Outlet Components
@@ -694,24 +877,48 @@ function MountInfo() {
 }
 ```
-See `/links` for full URL generation guide. The default server API is `ctx.reverse()`; in client components, receive URLs as props, loader data, or server-action return values — `reverse()` is not available in the browser.
+### useReverse(routes)
+Mount-aware local reverse for client components. Import the generated `routes` map from a `urls()` module's `.gen.ts` and call `reverse("name", params?)` — the leading dot is optional. Auto-fills params from `useParams()`; explicit params override.
+> Per-module `*.gen.ts` files are **CLI opt-in and not Vite-watched** — run `rango generate <urls-file>` (or wire it into `predev`) and re-run it whenever the module's routes change. See `/links` for the full generated-file setup and exposure-boundary rules.
+```tsx
+"use client";
+import { Link, useReverse } from "@rangojs/router/client";
+import { routes as blogRoutes } from "../urls/blog.gen.js";
+function BlogNav() {
+  const reverse = useReverse(blogRoutes);
+  return (
+    <nav>
+      <Link to={reverse("index")}>Blog</Link>
+      <Link to={reverse("post", { postId: "hello" })}>Post</Link>
+    </nav>
+  );
+}
+```
+See `/links` for the full URL generation guide. `ctx.reverse()` is server-only; on the client, prefer `useReverse(routes)` for in-module names and pass URLs as props for cross-module ones.
 ## Hook Summary
-| Hook                 | Purpose                           | Returns                                                            |
-| -------------------- | --------------------------------- | ------------------------------------------------------------------ |
-| `useParams()`        | Route params                      | `Readonly<T>` (default `Record<string, string>`) or selected value |
-| `usePathname()`      | Current pathname                  | `string`                                                           |
-| `useSearchParams()`  | URL search params                 | `ReadonlyURLSearchParams`                                          |
-| `useHref()`          | Mount-aware href                  | `(path) => string`                                                 |
-| `useMount()`         | Current include() mount path      | `string`                                                           |
-| `useNavigation()`    | Reactive navigation state         | state, location, isStreaming                                       |
-| `useRouter()`        | Stable router actions             | push, replace, refresh, prefetch, back, forward                    |
-| `useSegments()`      | URL path & segment IDs            | path, segmentIds, location                                         |
-| `useLinkStatus()`    | Link pending state                | { pending }                                                        |
-| `useLoader()`        | Loader data (strict)              | data, isLoading, error                                             |
-| `useFetchLoader()`   | Loader with on-demand fetch       | data, load, isLoading                                              |
-| `useHandle()`        | Accumulated handle data           | T (handle type)                                                    |
-| `useAction()`        | Server action state               | state, error, result                                               |
-| `useLocationState()` | History state (persists or flash) | T \| undefined                                                     |
-| `useClientCache()`   | Cache control                     | { clear }                                                          |
+| Hook                      | Purpose                                                        | Returns                                                            |
+| ------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `useParams()`             | Route params                                                   | `Readonly<T>` (default `Record<string, string>`) or selected value |
+| `usePathname()`           | Current pathname                                               | `string`                                                           |
+| `useSearchParams()`       | URL search params                                              | `ReadonlyURLSearchParams`                                          |
+| `useHref()`               | Mount-aware href                                               | `(path) => string`                                                 |
+| `useMount()`              | Current include() mount path                                   | `string`                                                           |
+| `useReverse()`            | Local reverse for imported routes                              | `(name, params?, search?) => string`                               |
+| `useNavigation()`         | Reactive navigation state                                      | state, location, isStreaming                                       |
+| `useRouter()`             | Stable router actions                                          | push, replace, refresh, prefetch, back, forward                    |
+| `useSegments()`           | URL path & segment IDs                                         | path, segmentIds, location                                         |
+| `useLinkStatus()`         | Link pending state                                             | { pending }                                                        |
+| `useLoader()`             | Loader data (strict)                                           | data, isLoading, error                                             |
+| `useFetchLoader()`        | Loader with on-demand fetch                                    | data, load, isLoading                                              |
+| `useRefreshLoaders()`     | Refresh cross-loader group(s)                                  | `() => (groups: string \| string[]) => Promise<void>`              |
+| `useHandle()`             | Accumulated handle data                                        | T (handle type)                                                    |
+| `useAction()`             | Server action state                                            | state, error, result                                               |
+| `useLocationState()`      | History state (persists or flash)                              | T \| undefined                                                     |
+| `invalidateClientCache()` | Force client caches to miss (function, not a hook; root entry) | `void`                                                             |