@rangojs/router 0.0.0-experimental.4 → 0.0.0-experimental.6

package/dist/vite/index.js

@@ -714,7 +714,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.4",
+  version: "0.0.0-experimental.6",
   type: "module",
   description: "Django-inspired RSC router with composable URL patterns",
   author: "Ivo Todorov",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.4",
+  "version": "0.0.0-experimental.6",
   "type": "module",
   "description": "Django-inspired RSC router with composable URL patterns",
   "author": "Ivo Todorov",

package/skills/router-setup/SKILL.md

@@ -97,6 +97,9 @@ interface RSCRouterOptions<TEnv> {
   // Theme configuration
   theme?: ThemeConfig | true;
 
+  // Connection warmup (default: true)
+  warmup?: boolean;
+
   // CSP nonce provider (for router.fetch)
   nonce?: (request: Request, env: TEnv) => string | true | Promise<string | true>;
 
@@ -313,3 +316,31 @@ const router = createRouter<AppEnv>({
   urls: urlpatterns,
 });
 ```
+
+## Connection Warmup
+
+Enabled by default. Keeps TCP+TLS connections alive so navigations after idle periods
+don't pay handshake costs.
+
+After 60s of no user interaction, the connection is marked cold. When the user returns
+(tab becomes visible or first mouse/touch), a `HEAD ?_rsc_warmup` request re-establishes
+the TLS connection before the next navigation. The server responds with 204 No Content
+before any middleware or routing runs.
+
+```typescript
+// Enabled by default
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+});
+
+// Disable warmup
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  warmup: false,
+});
+```
+
+The warmup request is relative to the current page path, so it works correctly
+with subpath deployments (reverse proxy, base path).

package/src/browser/react/NavigationProvider.tsx

@@ -120,6 +120,12 @@ export interface NavigationProviderProps {
    * Only used when themeConfig is provided
    */
   initialTheme?: Theme;
+
+  /**
+   * Whether connection warmup is enabled.
+   * When true, keeps TLS alive by sending HEAD requests after idle periods.
+   */
+  warmupEnabled?: boolean;
 }
 
 /**
@@ -150,6 +156,7 @@ export function NavigationProvider({
   bridge,
   themeConfig,
   initialTheme,
+  warmupEnabled,
 }: NavigationProviderProps): ReactNode {
   // Track current payload for rendering (this triggers re-renders)
   const [payload, setPayload] = useState(initialPayload);
@@ -182,6 +189,88 @@ export function NavigationProvider({
     []
   );
 
+  // Connection warmup: keep TLS alive after idle periods.
+  // After 60s of no user interaction, marks connection as "cold".
+  // On next interaction or visibility change, sends a HEAD request to warm TLS
+  // before the user actually clicks a link.
+  useEffect(() => {
+    if (!warmupEnabled) return;
+
+    const IDLE_TIMEOUT = 60_000;
+    const DEBOUNCE_DELAY = 150;
+
+    let idleTimer: ReturnType<typeof setTimeout> | undefined;
+    let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+    let isCold = false;
+    let warmupListenersAttached = false;
+
+    function sendWarmup() {
+      isCold = false;
+      fetch("/?_rsc_warmup", { method: "HEAD" }).catch(() => {});
+    }
+
+    function triggerWarmup() {
+      if (!isCold) return;
+      clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(() => {
+        sendWarmup();
+        detachWarmupListeners();
+        resetIdleTimer();
+      }, DEBOUNCE_DELAY);
+    }
+
+    function onVisibilityChange() {
+      if (document.visibilityState === "visible" && isCold) {
+        triggerWarmup();
+      }
+    }
+
+    function attachWarmupListeners() {
+      if (warmupListenersAttached) return;
+      warmupListenersAttached = true;
+      document.addEventListener("visibilitychange", onVisibilityChange);
+      document.addEventListener("mousemove", triggerWarmup, { once: true });
+      document.addEventListener("touchstart", triggerWarmup, { once: true });
+    }
+
+    function detachWarmupListeners() {
+      warmupListenersAttached = false;
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+      document.removeEventListener("mousemove", triggerWarmup);
+      document.removeEventListener("touchstart", triggerWarmup);
+    }
+
+    function markCold() {
+      isCold = true;
+      attachWarmupListeners();
+    }
+
+    function resetIdleTimer() {
+      clearTimeout(idleTimer);
+      isCold = false;
+      idleTimer = setTimeout(markCold, IDLE_TIMEOUT);
+    }
+
+    // Activity events that reset the idle timer
+    const activityEvents = ["mousemove", "keydown", "touchstart", "scroll"] as const;
+    const activityOptions: AddEventListenerOptions = { passive: true };
+
+    for (const event of activityEvents) {
+      document.addEventListener(event, resetIdleTimer, activityOptions);
+    }
+
+    resetIdleTimer();
+
+    return () => {
+      clearTimeout(idleTimer);
+      clearTimeout(debounceTimer);
+      detachWarmupListeners();
+      for (const event of activityEvents) {
+        document.removeEventListener(event, resetIdleTimer);
+      }
+    };
+  }, [warmupEnabled]);
+
   // Subscribe to UI updates (for re-rendering the tree)
   useEffect(() => {
     const unsubscribe = store.onUpdate((update) => {

package/src/browser/react/mount-context.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { createContext, type Context } from "react";
+import { createContext, createElement, type Context, type ReactNode } from "react";
 
 /**
  * Context for the current include() mount path.
@@ -12,3 +12,21 @@ import { createContext, type Context } from "react";
  * Default value "/" means root-level (no include wrapping).
  */
 export const MountContext: Context<string> = createContext<string>("/");
+
+/**
+ * Provider wrapper for MountContext.
+ *
+ * RSC server components cannot use MountContext.Provider directly because
+ * .Provider is a property on the context object, not a named export.
+ * Client reference proxies on the RSC server return undefined for property
+ * access. This wrapper is a proper "use client" export that RSC can reference.
+ */
+export function MountContextProvider({
+  value,
+  children,
+}: {
+  value: string;
+  children: ReactNode;
+}): ReactNode {
+  return createElement(MountContext, { value }, children);
+}

package/src/browser/rsc-router.tsx

@@ -13,7 +13,6 @@ import { createServerActionBridge } from "./server-action-bridge.js";
 import { createNavigationBridge } from "./navigation-bridge.js";
 import { NavigationProvider, initHandleDataSync, initSegmentsSync } from "./react/index.js";
 import { initThemeConfigSync } from "../theme/theme-context.js";
-import { initWarmupSync } from "../warmup/warmup-context.js";
 import type {
   RscPayload,
   RscBrowserDependencies,
@@ -105,6 +104,8 @@ export interface BrowserAppContext {
   themeConfig?: ResolvedThemeConfig | null;
   /** Initial theme from server */
   initialTheme?: Theme;
+  /** Whether connection warmup is enabled */
+  warmupEnabled?: boolean;
 }
 
 // Module-level state for the initialized app
@@ -158,9 +159,6 @@ export async function initBrowserApp(
   // Initialize theme config for MetaTags (must match SSR state)
   initThemeConfigSync(effectiveThemeConfig);
 
-  // Initialize warmup config for MetaTags (must match SSR state)
-  initWarmupSync(initialPayload.metadata?.warmupEnabled ?? true);
-
   // Initialize event controller with segment order (even without handles)
   eventController.setHandleData({}, initialPayload.metadata?.matched);
 
@@ -279,6 +277,7 @@ export async function initBrowserApp(
     initialTree,
     themeConfig: effectiveThemeConfig,
     initialTheme: effectiveInitialTheme,
+    warmupEnabled: initialPayload.metadata?.warmupEnabled ?? true,
   };
   browserAppContext = context;
 
@@ -334,7 +333,7 @@ export interface RSCRouterProps {}
  * ```
  */
 export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
-  const { store, eventController, bridge, initialPayload, initialTree, themeConfig, initialTheme } =
+  const { store, eventController, bridge, initialPayload, initialTree, themeConfig, initialTheme, warmupEnabled } =
     getBrowserAppContext();
 
   return (
@@ -345,6 +344,7 @@ export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
       bridge={bridge}
       themeConfig={themeConfig}
       initialTheme={initialTheme}
+      warmupEnabled={warmupEnabled}
     />
   );
 }

package/src/handles/MetaTags.tsx

@@ -30,8 +30,6 @@ import { Meta } from "./meta.js";
 import type { MetaDescriptor, MetaDescriptorBase } from "../router/types.js";
 import { getSSRThemeConfig } from "../theme/theme-context.js";
 import { generateThemeScript } from "../theme/theme-script.js";
-import { getSSRWarmupEnabled } from "../warmup/warmup-context.js";
-import { ConnectionWarmup } from "../warmup/connection-warmup.js";
 
 // Type guards for MetaDescriptorBase variants
 function hasCharSet(d: MetaDescriptorBase): d is { charSet: "utf-8" } {
@@ -175,7 +173,6 @@ function AsyncMetaTag({ promise, index }: { promise: Promise<MetaDescriptorBase>
 export function MetaTags(): React.ReactNode {
   const descriptors = useHandle(Meta) as MetaDescriptor[];
   const themeConfig = getSSRThemeConfig();
-  const warmupEnabled = getSSRWarmupEnabled();
 
   return (
     <>
@@ -191,7 +188,6 @@ export function MetaTags(): React.ReactNode {
         }
         return renderMetaDescriptor(descriptor, index);
       })}
-      {warmupEnabled && <ConnectionWarmup />}
     </>
   );
 }

package/src/rsc/handler.ts

@@ -977,7 +977,6 @@ export function createRSCHandler<
             handles: handleStore.stream(),
             version,
             themeConfig: router.themeConfig,
-            warmupEnabled: router.warmupEnabled,
             initialTheme: requireRequestContext().theme,
           },
         };
@@ -1035,7 +1034,6 @@ export function createRSCHandler<
           handles: handleStore.stream(),
           version,
           themeConfig: router.themeConfig,
-          warmupEnabled: router.warmupEnabled,
           initialTheme: requireRequestContext().theme,
         },
       };

package/src/segment-system.tsx

@@ -1,6 +1,6 @@
 import { createElement, type ReactNode, type ComponentType } from "react";
 import { OutletProvider } from "./client.js";
-import { MountContext } from "./browser/react/mount-context.js";
+import { MountContextProvider } from "./browser/react/mount-context.js";
 import type {
   ResolvedSegment,
   LoaderDataResult,
@@ -282,9 +282,12 @@ export async function renderSegments(
       });
     }
 
-    // Wrap with MountContext.Provider for include() scoped components
+    // Wrap with MountContextProvider for include() scoped components.
+    // Must use MountContextProvider (a proper "use client" export) instead of
+    // MountContext.Provider directly, because .Provider is a property on the
+    // context object and resolves to undefined through RSC client reference proxies.
     if (node.segment.mountPath && node.segment.type === "layout") {
-      content = createElement(MountContext.Provider, {
+      content = createElement(MountContextProvider, {
         value: node.segment.mountPath,
         children: content,
       });

package/src/warmup/connection-warmup.tsx

@@ -1,94 +0,0 @@
-"use client";
-
-/**
- * Connection warmup component.
- *
- * Keeps TCP+TLS connections alive so navigations after idle periods
- * don't pay DNS+TCP+TLS handshake costs. Sends a HEAD request with
- * ?_rsc_warmup when the connection goes cold and the user returns.
- *
- * Cold detection: 60s of no user interaction marks the connection as cold.
- * Warmup triggers: on visibility change or first user interaction after cold,
- * debounced 150ms, sends HEAD /?_rsc_warmup to re-establish TLS.
- */
-
-import { useEffect } from "react";
-
-const IDLE_TIMEOUT = 60_000;
-const DEBOUNCE_MS = 150;
-
-export function ConnectionWarmup(): null {
-  useEffect(() => {
-    let idleTimer: ReturnType<typeof setTimeout> | undefined;
-    let debounceTimer: ReturnType<typeof setTimeout> | undefined;
-    let isCold = false;
-    let warmupListenersAttached = false;
-
-    // Reset idle timer on any activity
-    function resetIdleTimer(): void {
-      isCold = false;
-      clearTimeout(idleTimer);
-      idleTimer = setTimeout(() => {
-        isCold = true;
-        attachWarmupListeners();
-      }, IDLE_TIMEOUT);
-    }
-
-    // Send the warmup HEAD request (debounced)
-    function triggerWarmup(): void {
-      if (!isCold) return;
-      clearTimeout(debounceTimer);
-      debounceTimer = setTimeout(() => {
-        fetch("/?_rsc_warmup", { method: "HEAD" }).catch(() => {});
-        isCold = false;
-        // Detach warmup listeners until next cold period
-        detachWarmupListeners();
-        resetIdleTimer();
-      }, DEBOUNCE_MS);
-    }
-
-    // Visibility change handler (fires even without mouse/touch)
-    function onVisibilityChange(): void {
-      if (document.visibilityState === "visible" && isCold) {
-        triggerWarmup();
-      }
-    }
-
-    // Warmup listeners are only active while cold
-    function attachWarmupListeners(): void {
-      if (warmupListenersAttached) return;
-      warmupListenersAttached = true;
-      document.addEventListener("visibilitychange", onVisibilityChange);
-      document.addEventListener("mousemove", triggerWarmup, { once: true });
-      document.addEventListener("touchstart", triggerWarmup, { once: true });
-    }
-
-    function detachWarmupListeners(): void {
-      if (!warmupListenersAttached) return;
-      warmupListenersAttached = false;
-      document.removeEventListener("visibilitychange", onVisibilityChange);
-      document.removeEventListener("mousemove", triggerWarmup);
-      document.removeEventListener("touchstart", triggerWarmup);
-    }
-
-    // Track activity for idle detection
-    const activityEvents = ["mousemove", "keydown", "touchstart", "scroll"] as const;
-    for (const event of activityEvents) {
-      document.addEventListener(event, resetIdleTimer, { passive: true });
-    }
-
-    // Start idle timer immediately
-    resetIdleTimer();
-
-    return () => {
-      clearTimeout(idleTimer);
-      clearTimeout(debounceTimer);
-      detachWarmupListeners();
-      for (const event of activityEvents) {
-        document.removeEventListener(event, resetIdleTimer);
-      }
-    };
-  }, []);
-
-  return null;
-}

package/src/warmup/warmup-context.ts

@@ -1,35 +0,0 @@
-"use client";
-
-/**
- * Warmup context for connection keep-alive configuration.
- *
- * Module-level state populated during browser init (initWarmupSync)
- * and read during SSR (getSSRWarmupEnabled) by MetaTags.
- */
-
-/**
- * SSR module-level state for warmup enabled flag.
- * Populated by initWarmupSync before React renders.
- * Used by MetaTags during SSR to conditionally render ConnectionWarmup.
- */
-let ssrWarmupEnabled = true;
-
-/**
- * Initialize warmup config synchronously for SSR.
- * Called before rendering to populate state for MetaTags.
- *
- * @param enabled - Whether connection warmup is enabled
- */
-export function initWarmupSync(enabled: boolean): void {
-  ssrWarmupEnabled = enabled;
-}
-
-/**
- * Get warmup enabled flag for SSR/hydration.
- * Used by MetaTags to conditionally render ConnectionWarmup.
- *
- * @returns Whether warmup is enabled
- */
-export function getSSRWarmupEnabled(): boolean {
-  return ssrWarmupEnabled;
-}