@rangojs/router 0.0.0-experimental.50 → 0.0.0-experimental.5035014b

package/dist/vite/index.named-routes.gen.ts

@@ -0,0 +1,103 @@
+// Auto-generated by @rangojs/router - do not edit
+export {};
+
+declare global {
+  namespace RSCRouter {
+    interface GeneratedRouteMap {
+      "apiShop.cart": "/api/shop/cart";
+      "apiShop.cartItem": "/api/shop/cart/:itemId";
+      "apiShop.catalog": "/api/shop/catalog";
+      "apiShop.health": "/api/shop/health";
+      "apiShop.product": "/api/shop/catalog/:productId";
+      "blog.index": "/blog";
+      "blog.post": "/blog/:postId";
+      "cacheStatus.notFound": "/cache-status/not-found";
+      "cacheStatus.redirect": "/cache-status/redirect";
+      "cacheStatus.redirectTarget": "/cache-status/redirect-target";
+      "cacheStatus.serverError": "/cache-status/server-error";
+      "cacheStatus.success": "/cache-status/success";
+      "cacheTest.cachedLoader": "/cache-test/cached-loader";
+      "cacheTest.interceptDetail": "/cache-test/intercept/:itemId";
+      "cacheTest.interceptIndex": "/cache-test/intercept";
+      "cacheTest.nonCachedLoader": "/cache-test/non-cached-loader";
+      "cacheTest.useLoaderDetail": "/cache-test/useloader/:itemId";
+      "cacheTest.useLoaderIndex": "/cache-test/useloader";
+      "changelog": "/changelog";
+      "docs": "/docs";
+      "docs.article": "/docs/:slug";
+      "errors.clientError": "/errors/client-error";
+      "errors.index": "/errors";
+      "errors.serverError": "/errors/server-error";
+      "errors.streamingError": "/errors/streaming-error";
+      "fetchLoader": "/fetch-loader";
+      "handlePassthrough": "/handle-passthrough";
+      "handlePassthroughAsync": "/handle-passthrough-async";
+      "hookTests.formAction": "/hook-tests/form-action";
+      "hookTests.index": "/hook-tests";
+      "hookTests.noLoader": "/hook-tests/no-loader";
+      "hookTests.routeA": "/hook-tests/route-a";
+      "hookTests.routeB": "/hook-tests/route-b";
+      "href.detail": "/href/:id";
+      "href.index": "/href";
+      "href.nested.index": "/href/nested";
+      "hydrationTest": "/hydration-test";
+      "index": "/";
+      "inlineAction": "/inline-action";
+      "loaderComposition": "/loader-composition";
+      "metaMerge.child": "/meta-merge/child";
+      "metaMerge.deep": "/meta-merge/deep/nested";
+      "metaMerge.index": "/meta-merge";
+      "metaTemplate.absolute": "/meta-template/absolute";
+      "metaTemplate.child": "/meta-template/child";
+      "metaTemplate.index": "/meta-template";
+      "metaTemplate.nested": "/meta-template/nested";
+      "metaTemplate.nestedChild": "/meta-template/nested/child";
+      "metaUnset.child": "/meta-unset/child";
+      "metaUnset.index": "/meta-unset";
+      "metaUnset.unsetThenSet": "/meta-unset/unset-then-set";
+      "middlewareTest.cookies": "/middleware-test/cookies";
+      "middlewareTest.errorHandler": "/middleware-test/error-handler/trigger";
+      "middlewareTest.index": "/middleware-test";
+      "middlewareTest.params": "/middleware-test/params/:paramId";
+      "middlewareTest.protected": "/middleware-test/protected";
+      "middlewareTest.protectedDashboard": "/middleware-test/protected/dashboard";
+      "middlewareTest.routeLevel": "/middleware-test/route-level";
+      "middlewareTest.routeLevelWithParams": "/middleware-test/route-level/:routeId";
+      "middlewareTest.sharedVars": "/middleware-test/shared-vars";
+      "negotiateJsonFirst": "/negotiate-test-json-first";
+      "negotiateJsonFirstRsc": "/negotiate-test-json-first";
+      "negotiateTest": "/negotiate-test";
+      "negotiateTestJson": "/negotiate-test";
+      "negotiateTestMd": "/negotiate-test";
+      "proactiveCache.index": "/proactive-cache";
+      "proactiveCache.itemA": "/proactive-cache/item-a";
+      "proactiveCache.itemB": "/proactive-cache/item-b";
+      "product.detail": "/product/:productId";
+      "progressiveEnhancement": "/progressive-enhancement";
+      "refTest.bothProps": "/ref-test/both-props";
+      "refTest.handleProp": "/ref-test/handle-prop";
+      "refTest.loaderProp": "/ref-test/loader-prop";
+      "responseInLayout": "/response-in-layout";
+      "responseInLayoutMd": "/response-in-layout-md";
+      "responseMwMd": "/response-mw/md-with-mw";
+      "responseMwNested": "/response-mw/nested";
+      "responseWrapAuto": "/response-wrap/auto";
+      "responseWrapCustom": "/response-wrap/custom-response";
+      "responseWrapHtml": "/response-wrap/html";
+      "responseWrapJsonHeaders": "/response-wrap/json-headers";
+      "responseWrapText": "/response-wrap/text";
+      "responseWrapWithHeaders": "/response-wrap/with-headers";
+      "responseWrapXml": "/response-wrap/xml";
+      "shopPlayground": "/shop-playground";
+      "slow": "/slow";
+      "slowProduct.detail": "/slow-product/:productId";
+      "slowStreaming": "/slow-streaming";
+      "slowStreamingSkipSsr": "/slow-streaming-skip-ssr";
+      "theme.index": "/theme";
+      "theme.toggle": "/theme/toggle";
+      "trailingSlash.always": "/ts-always";
+      "trailingSlash.ignore": "/ts-ignore";
+      "trailingSlash.never": "/ts-never";
+    }
+  }
+}

package/dist/vite/package-resolution.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Package Resolution Utilities
+ *
+ * Handles detection of workspace vs npm install context and generates
+ * appropriate aliases and exclude lists for Vite configuration.
+ */
+/**
+ * Get the published package name (e.g., "@rangojs/router")
+ */
+export declare function getPublishedPackageName(): string;
+/**
+ * Check if the package is installed from npm (scoped) vs workspace (unscoped)
+ *
+ * In workspace development:
+ * - Package is installed as "@rangojs/router" via pnpm workspace alias
+ * - The scoped name (@rangojs/router) doesn't exist in node_modules
+ *
+ * When installed from npm:
+ * - Package is installed as "@rangojs/router"
+ * - We need aliases to map "@rangojs/router/*" to "@rangojs/router/*"
+ */
+export declare function isInstalledFromNpm(): boolean;
+/**
+ * Check if we're in a monorepo/workspace development context
+ */
+export declare function isWorkspaceDevelopment(): boolean;
+/**
+ * Generate the list of modules to exclude from Vite's dependency optimization.
+ *
+ * We include both the published name and the virtual name because
+ * Vite's optimizer runs before alias resolution.
+ */
+export declare function getExcludeDeps(): string[];
+/**
+ * Generate aliases to map virtual package paths to the actual published package.
+ *
+ * Only needed when installed from npm, where the package is under @rangojs/router
+ * but virtual entries import from rsc-router/*.
+ *
+ * Returns empty object in workspace development where rsc-router resolves directly.
+ */
+export declare function getPackageAliases(): Record<string, string>;
+//# sourceMappingURL=package-resolution.d.ts.map

package/dist/vite/package-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-resolution.d.ts","sourceRoot":"","sources":["../../src/vite/package-resolution.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAI5C;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAmBD;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAczC;AAkBD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAc1D"}

package/dist/vite/package-resolution.js

@@ -0,0 +1,112 @@
+/**
+ * Package Resolution Utilities
+ *
+ * Handles detection of workspace vs npm install context and generates
+ * appropriate aliases and exclude lists for Vite configuration.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import packageJson from "../../package.json" with { type: "json" };
+/**
+ * The canonical name used in virtual entries (without scope)
+ */
+const VIRTUAL_PACKAGE_NAME = "@rangojs/router";
+/**
+ * Get the published package name (e.g., "@rangojs/router")
+ */
+export function getPublishedPackageName() {
+    return packageJson.name;
+}
+/**
+ * Check if the package is installed from npm (scoped) vs workspace (unscoped)
+ *
+ * In workspace development:
+ * - Package is installed as "@rangojs/router" via pnpm workspace alias
+ * - The scoped name (@rangojs/router) doesn't exist in node_modules
+ *
+ * When installed from npm:
+ * - Package is installed as "@rangojs/router"
+ * - We need aliases to map "@rangojs/router/*" to "@rangojs/router/*"
+ */
+export function isInstalledFromNpm() {
+    const packageName = getPublishedPackageName();
+    // Check if the scoped package exists in node_modules
+    return existsSync(resolve(process.cwd(), "node_modules", packageName));
+}
+/**
+ * Check if we're in a monorepo/workspace development context
+ */
+export function isWorkspaceDevelopment() {
+    return !isInstalledFromNpm();
+}
+/**
+ * Subpaths that need to be excluded from Vite's dependency optimization
+ * and potentially aliased
+ */
+const PACKAGE_SUBPATHS = [
+    "",
+    "/browser",
+    "/client",
+    "/server",
+    "/rsc",
+    "/ssr",
+    "/internal/deps/browser",
+    "/internal/deps/html-stream-client",
+    "/internal/deps/ssr",
+    "/internal/deps/rsc",
+];
+/**
+ * Generate the list of modules to exclude from Vite's dependency optimization.
+ *
+ * We include both the published name and the virtual name because
+ * Vite's optimizer runs before alias resolution.
+ */
+export function getExcludeDeps() {
+    const packageName = getPublishedPackageName();
+    const excludes = [];
+    for (const subpath of PACKAGE_SUBPATHS) {
+        // Add scoped package paths
+        excludes.push(`${packageName}${subpath}`);
+        // Add virtual/aliased paths (before alias resolution)
+        if (packageName !== VIRTUAL_PACKAGE_NAME) {
+            excludes.push(`${VIRTUAL_PACKAGE_NAME}${subpath}`);
+        }
+    }
+    return excludes;
+}
+/**
+ * Subpaths that need aliasing (subset of PACKAGE_SUBPATHS)
+ */
+const ALIAS_SUBPATHS = [
+    "/internal/deps/browser",
+    "/internal/deps/ssr",
+    "/internal/deps/rsc",
+    "/internal/deps/html-stream-client",
+    "/internal/deps/html-stream-server",
+    "/browser",
+    "/client",
+    "/server",
+    "/rsc",
+    "/ssr",
+];
+/**
+ * Generate aliases to map virtual package paths to the actual published package.
+ *
+ * Only needed when installed from npm, where the package is under @rangojs/router
+ * but virtual entries import from rsc-router/*.
+ *
+ * Returns empty object in workspace development where rsc-router resolves directly.
+ */
+export function getPackageAliases() {
+    if (isWorkspaceDevelopment()) {
+        // No aliases needed - rsc-router resolves directly
+        return {};
+    }
+    const packageName = getPublishedPackageName();
+    const aliases = {};
+    for (const subpath of ALIAS_SUBPATHS) {
+        aliases[`${VIRTUAL_PACKAGE_NAME}${subpath}`] = `${packageName}${subpath}`;
+    }
+    return aliases;
+}
+//# sourceMappingURL=package-resolution.js.map

package/dist/vite/package-resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-resolution.js","sourceRoot":"","sources":["../../src/vite/package-resolution.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,WAAW,MAAM,oBAAoB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAEnE;;GAEG;AACH,MAAM,oBAAoB,GAAG,iBAAiB,CAAC;AAE/C;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,WAAW,CAAC,IAAI,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,WAAW,GAAG,uBAAuB,EAAE,CAAC;IAC9C,qDAAqD;IACrD,OAAO,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC;AACzE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,CAAC,kBAAkB,EAAE,CAAC;AAC/B,CAAC;AAED;;;GAGG;AACH,MAAM,gBAAgB,GAAG;IACvB,EAAE;IACF,UAAU;IACV,SAAS;IACT,SAAS;IACT,MAAM;IACN,MAAM;IACN,wBAAwB;IACxB,mCAAmC;IACnC,oBAAoB;IACpB,oBAAoB;CACZ,CAAC;AAEX;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,WAAW,GAAG,uBAAuB,EAAE,CAAC;IAC9C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,KAAK,MAAM,OAAO,IAAI,gBAAgB,EAAE,CAAC;QACvC,2BAA2B;QAC3B,QAAQ,CAAC,IAAI,CAAC,GAAG,WAAW,GAAG,OAAO,EAAE,CAAC,CAAC;QAC1C,sDAAsD;QACtD,IAAI,WAAW,KAAK,oBAAoB,EAAE,CAAC;YACzC,QAAQ,CAAC,IAAI,CAAC,GAAG,oBAAoB,GAAG,OAAO,EAAE,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,cAAc,GAAG;IACrB,wBAAwB;IACxB,oBAAoB;IACpB,oBAAoB;IACpB,mCAAmC;IACnC,mCAAmC;IACnC,UAAU;IACV,SAAS;IACT,SAAS;IACT,MAAM;IACN,MAAM;CACE,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,sBAAsB,EAAE,EAAE,CAAC;QAC7B,mDAAmD;QACnD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,WAAW,GAAG,uBAAuB,EAAE,CAAC;IAC9C,MAAM,OAAO,GAA2B,EAAE,CAAC;IAE3C,KAAK,MAAM,OAAO,IAAI,cAAc,EAAE,CAAC;QACrC,OAAO,CAAC,GAAG,oBAAoB,GAAG,OAAO,EAAE,CAAC,GAAG,GAAG,WAAW,GAAG,OAAO,EAAE,CAAC;IAC5E,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/vite/virtual-entries.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Default virtual entry file contents for rsc-router.
+ * These are used when users don't provide their own entry files.
+ */
+export declare const VIRTUAL_ENTRY_BROWSER: string;
+export declare const VIRTUAL_ENTRY_SSR: string;
+/**
+ * Generate the RSC entry content with the specified router path
+ */
+export declare function getVirtualEntryRSC(routerPath: string): string;
+/**
+ * Virtual module IDs
+ */
+export declare const VIRTUAL_IDS: {
+    readonly browser: "virtual:rsc-router/entry.browser.js";
+    readonly ssr: "virtual:rsc-router/entry.ssr.js";
+    readonly rsc: "virtual:rsc-router/entry.rsc.js";
+    readonly version: "@rangojs/router:version";
+};
+/**
+ * Virtual module content for version.
+ * Exports VERSION - a timestamp that changes on server restart (dev) or at build time (production).
+ */
+export declare function getVirtualVersionContent(version: string): string;
+//# sourceMappingURL=virtual-entries.d.ts.map

package/dist/vite/virtual-entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-entries.d.ts","sourceRoot":"","sources":["../../src/vite/virtual-entries.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,qBAAqB,EAAE,MA+B5B,CAAC;AAET,eAAO,MAAM,iBAAiB,EAAE,MAaxB,CAAC;AAET;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAuC7D;AAED;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;CAKd,CAAC;AAEX;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhE"}

package/dist/vite/virtual-entries.js

@@ -0,0 +1,110 @@
+/**
+ * Default virtual entry file contents for rsc-router.
+ * These are used when users don't provide their own entry files.
+ */
+export const VIRTUAL_ENTRY_BROWSER = `
+import {
+  createFromReadableStream,
+  createFromFetch,
+  setServerCallback,
+  encodeReply,
+  createTemporaryReferenceSet,
+} from "@rangojs/router/internal/deps/browser";
+import { createElement, StrictMode } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { rscStream } from "@rangojs/router/internal/deps/html-stream-client";
+import { initBrowserApp, RSCRouter } from "@rangojs/router/browser";
+
+async function initializeApp() {
+  const deps = {
+    createFromFetch,
+    createFromReadableStream,
+    encodeReply,
+    setServerCallback,
+    createTemporaryReferenceSet,
+  };
+
+  await initBrowserApp({ rscStream, deps });
+
+  hydrateRoot(
+    document,
+    createElement(StrictMode, null, createElement(RSCRouter))
+  );
+}
+
+initializeApp().catch(console.error);
+`.trim();
+export const VIRTUAL_ENTRY_SSR = `
+import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
+import { renderToReadableStream } from "react-dom/server.edge";
+import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
+import { createSSRHandler } from "@rangojs/router/ssr";
+
+export const renderHTML = createSSRHandler({
+  createFromReadableStream,
+  renderToReadableStream,
+  injectRSCPayload,
+  loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+});
+`.trim();
+/**
+ * Generate the RSC entry content with the specified router path
+ */
+export function getVirtualEntryRSC(routerPath) {
+    return `
+import {
+  renderToReadableStream,
+  decodeReply,
+  createTemporaryReferenceSet,
+  loadServerAction,
+  decodeAction,
+  decodeFormState,
+} from "@rangojs/router/internal/deps/rsc";
+import { router } from "${routerPath}";
+import { createRSCHandler } from "@rangojs/router/internal/rsc-handler";
+import { VERSION } from "@rangojs/router:version";
+
+// Import loader manifest to ensure all fetchable loaders are registered at startup
+// This is critical for serverless/multi-process deployments where the loader module
+// might not be imported before a GET request arrives
+import "virtual:rsc-router/loader-manifest";
+
+// Import pre-generated route manifest so href() works immediately on cold start.
+// In build mode, this contains the full route map generated at build time.
+// In dev mode, this is a no-op (manifest is populated in-memory by the discovery plugin).
+import "virtual:rsc-router/routes-manifest";
+
+export default createRSCHandler({
+  router,
+  version: VERSION,
+  deps: {
+    renderToReadableStream,
+    decodeReply,
+    createTemporaryReferenceSet,
+    loadServerAction,
+    decodeAction,
+    decodeFormState,
+  },
+  loadSSRModule: () =>
+    import.meta.viteRsc.loadModule("ssr", "index"),
+});
+`.trim();
+}
+/**
+ * Virtual module IDs
+ */
+export const VIRTUAL_IDS = {
+    browser: "virtual:rsc-router/entry.browser.js",
+    ssr: "virtual:rsc-router/entry.ssr.js",
+    rsc: "virtual:rsc-router/entry.rsc.js",
+    version: "@rangojs/router:version",
+};
+/**
+ * Virtual module content for version.
+ * Exports VERSION - a timestamp that changes on server restart (dev) or at build time (production).
+ */
+export function getVirtualVersionContent(version) {
+    return `export const VERSION = ${JSON.stringify(version)};`;
+}
+//# sourceMappingURL=virtual-entries.js.map

package/dist/vite/virtual-entries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-entries.js","sourceRoot":"","sources":["../../src/vite/virtual-entries.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+B5C,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,CAAC,MAAM,iBAAiB,GAAW;;;;;;;;;;;;;CAaxC,CAAC,IAAI,EAAE,CAAC;AAET;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAkB;IACnD,OAAO;;;;;;;;;0BASiB,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BnC,CAAC,IAAI,EAAE,CAAC;AACT,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,OAAO,EAAE,qCAAqC;IAC9C,GAAG,EAAE,iCAAiC;IACtC,GAAG,EAAE,iCAAiC;IACtC,OAAO,EAAE,yBAAyB;CAC1B,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAe;IACtD,OAAO,0BAA0B,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC;AAC9D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.50",
+  "version": "0.0.0-experimental.5035014b",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/cache-guide/SKILL.md

@@ -162,6 +162,38 @@ middleware(async (ctx, next) => {
 });
 ```
 
+## Context Variable Cache Safety
+
+Context variables created with `createVar()` are cacheable by default and can
+be read freely inside `cache()` and `"use cache"` scopes. Non-cacheable vars
+throw at read time to prevent request-specific data from being captured.
+
+There are two ways to mark a value as non-cacheable:
+
+```typescript
+// Var-level policy — inherently request-specific data
+const Session = createVar<SessionData>({ cache: false });
+
+// Write-level escalation — this specific write is non-cacheable
+ctx.set(Theme, derivedTheme, { cache: false });
+```
+
+"Least cacheable wins": if either the var definition or the `ctx.set()` call
+specifies `cache: false`, the value is non-cacheable.
+
+**Behavior inside cache scopes:**
+
+| Operation                           | Inside `cache()` / `"use cache"` |
+| ----------------------------------- | -------------------------------- |
+| `ctx.get(cacheableVar)`             | Allowed                          |
+| `ctx.get(nonCacheableVar)`          | Throws                           |
+| `ctx.set(var, value)` (cacheable)   | Allowed                          |
+| `ctx.header()`, `ctx.cookie()`, etc | Throws (response side effects)   |
+
+Write is dumb — `ctx.set()` stores the cache metadata but does not enforce.
+Enforcement happens at read time (`ctx.get()`), where ALS detects the cache
+scope and rejects non-cacheable reads.
+
 ## Loaders Are Always Fresh
 
 Loaders are **never cached** by route-level `cache()`. Even on a full cache hit

package/skills/caching/SKILL.md

@@ -173,6 +173,14 @@ const router = createRouter<AppBindings>({
 KV entries require `expirationTtl >= 60s`. Short-lived entries (< 60s total TTL)
 are only cached in L1.
 
+## Context Variables Inside Cache Boundaries
+
+Context variables (`createVar`) are cacheable by default and can be read and
+written inside `cache()` scopes. Variables marked with `{ cache: false }` (at
+the var level or write level) throw when read inside a cache scope. Response
+side effects (`ctx.header()`, `ctx.cookie()`) always throw inside cache
+boundaries. See `/cache-guide` for the full cache safety table.
+
 ## Nested Cache Boundaries
 
 Override cache settings for specific sections:

package/skills/loader/SKILL.md

@@ -65,24 +65,10 @@ export const urlpatterns = urls(({ path, loader }) => [
 
 ## Consuming Loader Data
 
-Loaders are the **live data layer** — they resolve fresh on every request.
-The way you consume them depends on whether you're in a server component
-(route handler) or a client component.
-
-> **IMPORTANT: Prefer consuming loaders in client components.** Keeping data
-> fetching in loaders and consumption in client components creates a clean
-> separation: the server-side handler renders static markup that can be
-> freely cached with `cache()`, while loader data stays fresh on every
-> request. When you consume loaders in server handlers via `ctx.use()`, the
-> handler output depends on the loader data, which means caching the handler
-> also caches the data — defeating the purpose of the live data layer.
-
-### In Client Components (Preferred)
-
-Client components use `useLoader()` from `@rangojs/router/client`.
-The loader **must** be registered with `loader()` in the route's DSL
-segments so the framework knows to resolve it during SSR and stream
-the data to the client:
+Register loaders with `loader()` in the DSL and consume them in client
+components with `useLoader()`. This is the recommended pattern — it keeps
+data fetching on the server and consumption on the client, with a clean
+separation that works correctly with `cache()`.
 
 ```typescript
 "use client";
@@ -96,40 +82,60 @@ function ProductDetails() {
 ```
 
 ```typescript
-// Route definition — loader() registration required for client consumption
+// Route definition — loader() registration required
 path("/product/:slug", ProductPage, { name: "product" }, () => [
-  loader(ProductLoader), // Required for useLoader() in client components
+  loader(ProductLoader),
 ]);
 ```
 
-### In Route Handlers (Server Components)
+DSL loaders are the **live data layer** — they resolve fresh on every
+request, even when the route is inside a `cache()` boundary. The router
+excludes them from the segment cache at storage time and re-resolves them
+on retrieval. This means `cache()` gives you cached UI + fresh data by
+default.
 
-In server components, use `ctx.use(Loader)` directly in the route handler.
-This doesn't require `loader()` registration in the DSL — it works
-standalone. **However**, prefer client-side consumption when possible (see
-note above).
+### Cache safety
 
-```typescript
-import { ProductLoader } from "./loaders/product";
+DSL loaders can safely read `createVar({ cache: false })` variables
+because they are always resolved fresh. The read guard is bypassed for
+loader functions — they never produce stale data.
+
+### ctx.use(Loader) — escape hatch
+
+For cases where you need loader data in the server handler itself (e.g.,
+to set ctx variables or make routing decisions), use `ctx.use(Loader)`:
 
-// Route handler — server component
+```typescript
 path("/product/:slug", async (ctx) => {
   const { product } = await ctx.use(ProductLoader);
-  return <h1>{product.name}</h1>;
-}, { name: "product" })
+  ctx.set(Product, product); // make available to children
+  return <ProductPage />;
+}, { name: "product" }, () => [
+  loader(ProductLoader), // still register for client consumption
+])
 ```
 
-When you do register with `loader()` in the DSL, `ctx.use()` returns the
+When you register with `loader()` in the DSL, `ctx.use()` returns the
 same memoized result — loaders never run twice per request.
 
+**Limitations of ctx.use(Loader):**
+
+- The handler output depends on the loader data. If the route is inside
+  `cache()`, the handler is cached with the loader result baked in —
+  defeating the live data guarantee.
+- Non-cacheable variable reads (`createVar({ cache: false })`) inside the
+  handler still throw, even if the data came from a loader.
+- Prefer DSL `loader()` + client `useLoader()` for data that depends on
+  non-cacheable context variables.
+
 **Never use `useLoader()` in server components** — it is a client-only API.
 
 ### Summary
 
-| Context                      | API                 | `loader()` DSL required? |
-| ---------------------------- | ------------------- | ------------------------ |
-| Client component (preferred) | `useLoader(Loader)` | **Yes**                  |
-| Route handler (server)       | `ctx.use(Loader)`   | No                       |
+| Pattern                | API                 | Cache-safe | Recommended |
+| ---------------------- | ------------------- | ---------- | ----------- |
+| DSL + client component | `useLoader(Loader)` | Yes        | Yes         |
+| Handler escape hatch   | `ctx.use(Loader)`   | No         | When needed |
 
 ## Loader Context
 
@@ -548,7 +554,7 @@ export const ProductLoader = createLoader(async (ctx) => {
     .first();
 
   if (!product) {
-    throw new Response("Product not found", { status: 404 });
+    notFound("Product not found");
   }
 
   return { product };
@@ -564,10 +570,9 @@ export const CartLoader = createLoader(async (ctx) => {
   return { cart };
 });
 
-// urls.tsx
+// urls.tsx — register loaders in the DSL
 export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalidate }) => [
   layout(<ShopLayout />, () => [
-    // Shared cart loader for all shop routes
     loader(CartLoader, () => [
       revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
     ]),
@@ -579,17 +584,22 @@ export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalid
   ]),
 ]);
 
-// pages/product.tsx — server component (route handler)
+// components/ProductDetails.tsx — consume in client component
+"use client";
+import { useLoader } from "@rangojs/router/client";
 import { ProductLoader, CartLoader } from "./loaders/shop";
 
-async function ProductPage(ctx) {
-  const { product } = await ctx.use(ProductLoader);
-  const { cart } = await ctx.use(CartLoader);
+function ProductDetails() {
+  const { data: { product } } = useLoader(ProductLoader);
+  const { data: { cart } } = useLoader(CartLoader);
 
   return (
     <div>
       <h1>{product.name}</h1>
-      <AddToCartButton productId={product.id} inCart={cart?.items.includes(product.id)} />
+      <AddToCartButton
+        productId={product.id}
+        inCart={cart?.items.includes(product.id)}
+      />
     </div>
   );
 }