@rangojs/router 0.0.0-experimental.45 → 0.0.0-experimental.4525a442

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.45",
+  "version": "0.0.0-experimental.4525a442",
   "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
 
@@ -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>
   );
 }

package/skills/parallel/SKILL.md

@@ -92,6 +92,73 @@ path("/dashboard/:id", (ctx) => {
 ])
 ```
 
+## Setting Handles (Meta, Breadcrumbs)
+
+Parallel slot handlers can call `ctx.use(Meta)` or `ctx.use(Breadcrumbs)` to
+push handle data. The data is associated with the **parent** layout or route
+segment, not the parallel segment itself. This is because parallels execute
+after their parent handler and inherit its segment scope.
+
+This works well for document-level metadata — the handle data follows the
+parent's lifecycle (appears when the parent is mounted, removed when it
+unmounts).
+
+```typescript
+parallel({
+  "@meta": (ctx) => {
+    const meta = ctx.use(Meta);
+    meta({ title: "Product Detail" });
+    meta({ name: "description", content: "..." });
+    return null; // UI-less slot, only sets metadata
+  },
+  "@sidebar": (ctx) => <Sidebar />,
+})
+```
+
+Multiple parallels on the same parent can each push handle data — they all
+accumulate under the parent segment ID.
+
+### Pattern: `@meta` slot for per-route metadata overrides
+
+A dedicated `@meta` parallel slot lets routes define metadata separately from
+their handler logic. The layout sets defaults via a title template, and each
+route overrides via its own `@meta` slot. Since child segments push after
+parents and `collectMeta` uses last-wins deduplication, overrides work
+naturally.
+
+```typescript
+// Layout sets defaults
+layout((ctx) => {
+  ctx.use(Meta)({ title: { template: "%s | Store", default: "Store" } });
+  return <StoreLayout />;
+}, () => [
+  // Route with @meta override — decoupled from handler rendering
+  path("/:slug", ProductPage, { name: "product" }, () => [
+    parallel({
+      "@meta": async (ctx) => {
+        const product = await ctx.use(ProductLoader);
+        const meta = ctx.use(Meta);
+        meta({ title: product.name });
+        meta({ name: "description", content: product.description });
+        meta({
+          "script:ld+json": {
+            "@context": "https://schema.org",
+            "@type": "Product",
+            name: product.name,
+            description: product.description,
+          },
+        });
+        return null; // UI-less slot
+      },
+    }),
+  ]),
+])
+```
+
+This keeps the route handler focused on rendering UI while metadata
+(title, description, Open Graph, JSON-LD) lives in a composable slot that
+can be added, removed, or swapped per route without touching the handler.
+
 ## Parallel Routes with Loaders
 
 Add loaders and loading states to parallel routes:
@@ -109,6 +176,65 @@ parallel(
 )
 ```
 
+### Streaming Behavior
+
+Parallels with `loading()` are **independent streaming units**. They don't
+block the parent layout or sibling routes during SSR:
+
+- **With `loading()`**: The skeleton renders immediately. The loader runs
+  in the background and streams data to the client when ready. The rest
+  of the page (layout, route content, other parallels) renders without
+  waiting.
+- **Without `loading()`**: The parallel's loaders block the parent layout's
+  rendering. Use this when the data must be available before the page
+  paints (e.g., critical above-the-fold content).
+- **SPA navigation**: Parallel loaders resolve in the background. The
+  existing parallel UI stays visible — no skeleton flash on route changes
+  within the same layout.
+
+```typescript
+// Sidebar streams independently — page renders immediately
+parallel(
+  { "@sidebar": () => <Sidebar /> },
+  () => [loader(SlowSidebarLoader), loading(<SidebarSkeleton />)]
+)
+
+// Cart data blocks layout — must be ready before paint
+parallel(
+  { "@cartBadge": () => <CartBadge /> },
+  () => [loader(CartCountLoader)]  // No loading() = awaited
+)
+```
+
+## Slot Override Semantics
+
+When multiple `parallel()` calls define the same slot name, **the last
+definition wins**. Earlier definitions of that slot are removed. Other
+slots from the earlier call are preserved.
+
+This enables composition patterns where included routes override
+parent-defined slots:
+
+```typescript
+layout(DashboardLayout, () => [
+  // Base slots
+  parallel({
+    "@sidebar": () => <DefaultSidebar />,
+    "@footer": () => <Footer />,
+  }),
+
+  // Override just @sidebar — @footer is preserved
+  parallel({ "@sidebar": () => <CustomSidebar /> }),
+
+  path("/", DashboardIndex, { name: "index" }),
+])
+```
+
+After resolution, the layout has two parallel entries:
+
+- `{ "@footer": () => <Footer /> }` (first call, `@sidebar` removed)
+- `{ "@sidebar": () => <CustomSidebar /> }` (second call, wins)
+
 ## Multiple Parallel Slots
 
 ```typescript

package/skills/route/SKILL.md

@@ -181,6 +181,37 @@ String keys still work (`ctx.set("key", value)` / `ctx.get("key")`), but
 Only route handlers and middleware can call `ctx.set()`. Layouts, parallels,
 and intercepts can only read via `ctx.get()`.
 
+#### Non-cacheable context variables
+
+Mark a var as non-cacheable when it holds inherently request-specific data
+(sessions, auth tokens, per-request IDs). There are two ways:
+
+```typescript
+// Var-level: every value written to this var is non-cacheable
+const Session = createVar<SessionData>({ cache: false });
+
+// Write-level: escalate a normally-cacheable var for this specific write
+const Theme = createVar<string>();
+ctx.set(Theme, userTheme, { cache: false });
+```
+
+"Least cacheable wins" — if either the var definition or the write site says
+`cache: false`, the value is non-cacheable.
+
+Reading a non-cacheable var inside `cache()` or `"use cache"` throws at
+runtime. This prevents request-specific data from leaking into cached output:
+
+```typescript
+// This throws — Session is non-cacheable
+async function CachedWidget(ctx) {
+  "use cache";
+  const session = ctx.get(Session); // Error: non-cacheable var read inside cache scope
+  return <Widget />;
+}
+```
+
+Cacheable vars (the default) can be read freely inside cache scopes.
+
 ### Revalidation Contracts for Handler Data
 
 Handler-first guarantees apply within a single full render pass. For partial

package/skills/typesafety/SKILL.md

@@ -369,8 +369,18 @@ interface PaginationData {
   perPage: number;
 }
 export const Pagination = createVar<PaginationData>();
+
+// Non-cacheable var — reading inside cache() or "use cache" throws at runtime
+const Session = createVar<SessionData>({ cache: false });
 ```
 
+`createVar` accepts an optional options object. The `cache` option (default
+`true`) controls whether the var's values can be read inside cache scopes.
+Write-level escalation is also supported: `ctx.set(Var, value, { cache: false })`
+marks a specific write as non-cacheable even if the var itself is cacheable.
+"Least cacheable wins" — if either says `cache: false`, the value throws on
+read inside `cache()` or `"use cache"`.
+
 ### Producer (handler or middleware)
 
 ```typescript