@rangojs/router 0.0.0-experimental.11 → 0.0.0-experimental.111

package/src/vite/utils/shared-utils.ts

@@ -0,0 +1,174 @@
+import type { Plugin } from "vite";
+import * as Vite from "vite";
+import { getPublishedPackageName } from "./package-resolution.js";
+import { performanceTracksOptimizeDepsPlugin } from "../plugins/performance-tracks.js";
+import {
+  VIRTUAL_ENTRY_BROWSER,
+  VIRTUAL_ENTRY_SSR,
+  getVirtualEntryRSC,
+  getVirtualVersionContent,
+  VIRTUAL_IDS,
+} from "../plugins/virtual-entries.js";
+
+/**
+ * Rolldown plugin to provide the version virtual module during dependency
+ * optimization. Vite 8 optimizes deps with Rolldown (a Rollup-style plugin
+ * pipeline that is separate from the main plugin set), so this is a
+ * resolveId/load plugin under optimizeDeps.rolldownOptions. Any dep pulled into
+ * optimization that imports the version virtual module gets a "dev" stub here;
+ * the real VERSION is injected into runtime modules by the version plugin.
+ */
+const versionRolldownPlugin = {
+  name: "@rangojs/router-version",
+  resolveId(id: string): string | undefined {
+    if (id === VIRTUAL_IDS.version) return "\0" + VIRTUAL_IDS.version;
+    return undefined;
+  },
+  load(id: string): string | undefined {
+    if (id === "\0" + VIRTUAL_IDS.version) {
+      return getVirtualVersionContent("dev");
+    }
+    return undefined;
+  },
+};
+
+/**
+ * Shared Rolldown options for dependency optimization (Vite 8).
+ * Includes the version stub plugin and the performance-tracks RSDW patch.
+ */
+export const sharedRolldownOptions: {
+  plugins: any[];
+} = {
+  plugins: [versionRolldownPlugin, performanceTracksOptimizeDepsPlugin()],
+};
+
+/**
+ * Create a virtual modules plugin for default entry files.
+ * Provides virtual module content when entries use VIRTUAL_IDS (no custom entry configured).
+ */
+export function createVirtualEntriesPlugin(
+  entries: { client: string; ssr: string; rsc?: string },
+  routerPathRef?: { path?: string },
+): Plugin {
+  // Build virtual modules map based on which entries use virtual IDs
+  const virtualModules: Record<string, string> = {};
+
+  if (entries.client === VIRTUAL_IDS.browser) {
+    virtualModules[VIRTUAL_IDS.browser] = VIRTUAL_ENTRY_BROWSER;
+  }
+  if (entries.ssr === VIRTUAL_IDS.ssr) {
+    virtualModules[VIRTUAL_IDS.ssr] = VIRTUAL_ENTRY_SSR;
+  }
+
+  // RSC entry is resolved lazily in load() because routerPath may be
+  // set after plugin creation (e.g. by the auto-discover config() hook).
+  // Track all known virtual IDs for resolveId (content is separate).
+  const knownIds = new Set(Object.keys(virtualModules));
+  if (entries.rsc === VIRTUAL_IDS.rsc) {
+    knownIds.add(VIRTUAL_IDS.rsc);
+  }
+
+  return {
+    name: "@rangojs/router:virtual-entries",
+    enforce: "pre",
+
+    resolveId(id) {
+      if (knownIds.has(id)) {
+        return "\0" + id;
+      }
+      // Handle if the id already has the null prefix (RSC plugin wrapper imports)
+      if (id.startsWith("\0") && knownIds.has(id.slice(1))) {
+        return id;
+      }
+      return null;
+    },
+
+    load(id) {
+      if (id.startsWith("\0virtual:rsc-router/")) {
+        const virtualId = id.slice(1);
+        if (virtualId in virtualModules) {
+          return virtualModules[virtualId];
+        }
+        // Lazy RSC entry: routerPath may have been set by a config() hook
+        if (virtualId === VIRTUAL_IDS.rsc && routerPathRef?.path) {
+          const raw = routerPathRef.path.startsWith(".")
+            ? "/" + routerPathRef.path.slice(2) // ./src/router.tsx -> /src/router.tsx
+            : routerPathRef.path;
+          // Normalize backslashes for Windows (path.join/slice preserve native separators)
+          const absoluteRouterPath = raw.replaceAll("\\", "/");
+          return getVirtualEntryRSC(absoluteRouterPath);
+        }
+      }
+      return null;
+    },
+  };
+}
+
+/**
+ * Rollup onwarn handler that suppresses known harmless warnings:
+ * - "use client" directives: handled by the RSC plugin, not relevant to Rollup
+ * - sourcemap errors: caused by "use client" directive at line 1:0 confusing sourcemap resolution
+ * - sourcemap incomplete: plugins that transform without generating sourcemaps (router + RSC plugin)
+ * - dynamic/static mixed imports: expected for router internals (e.g. request-context, cache-scope).
+ *   Under Rolldown (Vite 8) this surfaces as the INEFFECTIVE_DYNAMIC_IMPORT code emitted directly
+ *   by the bundler, rather than the vite:reporter message handled below (Rollup/Vite 7 shape).
+ * - empty bundle: @vitejs/plugin-rsc scan build (step 1/5) produces an empty "index" chunk
+ *   because the RSC entry is fully externalized during client-reference analysis
+ */
+export function onwarn(
+  warning: Vite.Rollup.RollupLog,
+  defaultHandler: (warning: Vite.Rollup.RollupLog) => void,
+): void {
+  if (
+    warning.code === "MODULE_LEVEL_DIRECTIVE" ||
+    warning.code === "SOURCEMAP_ERROR" ||
+    warning.code === "EMPTY_BUNDLE" ||
+    warning.code === "INEFFECTIVE_DYNAMIC_IMPORT"
+  ) {
+    return;
+  }
+  // @vitejs/plugin-rsc@0.5.14: rsc:virtual:vite-rsc/assets-manifest renderChunk
+  // returns { code } without map, causing Rollup to warn about incorrect sourcemaps.
+  // This is harmless (simple string replacement). Remove this suppression if a
+  // future version of @vitejs/plugin-rsc fixes the missing sourcemap.
+  if (warning.message?.includes("Sourcemap is likely to be incorrect")) {
+    return;
+  }
+  if (
+    warning.plugin === "vite:reporter" &&
+    warning.message?.includes(
+      "dynamic import will not move module into another chunk",
+    )
+  ) {
+    return;
+  }
+  defaultHandler(warning);
+}
+
+/**
+ * Manual chunks configuration for client build.
+ * Splits React and router packages into separate chunks for better caching.
+ */
+export function getManualChunks(id: string): string | undefined {
+  const normalized = Vite.normalizePath(id);
+
+  if (
+    normalized.includes("node_modules/react/") ||
+    normalized.includes("node_modules/react-dom/") ||
+    normalized.includes("node_modules/react-server-dom-webpack/") ||
+    normalized.includes("node_modules/@vitejs/plugin-rsc/")
+  ) {
+    return "react";
+  }
+  // Use dynamic package name from package.json
+  // Check both npm install path and workspace symlink resolved path
+  const packageName = getPublishedPackageName();
+  if (
+    normalized.includes(`node_modules/${packageName}/`) ||
+    normalized.includes("packages/rsc-router/") ||
+    normalized.includes("packages/rangojs-router/")
+  ) {
+    return "router";
+  }
+  return undefined;
+}

package/CLAUDE.md

@@ -1,43 +0,0 @@
-# @rangojs/router
-
-Run `/rango` first to understand the API. Skills are in `node_modules/@rangojs/router/skills/`.
-
-## Tree-Structure-Critical Files (DO NOT MODIFY without understanding)
-
-The following files control the React tree structure. Changing the tree structure
-(element types, nesting depth, or keys at any position) between SSR, navigation,
-and action renders will cause React to remount components, destroying client state
-like `useActionState`, refs, and local state. This is extremely hard to debug.
-
-**Protected files:**
-
-- `src/segment-system.tsx` - `renderSegments()` builds the React tree from segments.
-  The `loading` property determines tree structure:
-  - `undefined` / `null` -> OutletProvider directly (no boundary)
-  - `false` -> LoaderBoundary + OutletProvider (boundary, no RouteContentWrapper)
-  - truthy (ReactNode) -> LoaderBoundary + OutletProvider + RouteContentWrapper
-
-- `src/route-content-wrapper.tsx` - `LoaderBoundary` and `RouteContentWrapper`.
-  These add structural depth (Suspense boundaries) to the React tree.
-
-- `src/browser/server-action-bridge.ts` - Merges server action segments with
-  cached segments. Must preserve cached `loading` values to prevent tree drift.
-
-- `src/browser/partial-update.ts` - Merges navigation segments with cached segments.
-
-**Rules:**
-
-1. Never change the conditional logic in `renderSegments()` that decides between
-   LoaderBoundary/RouteContentWrapper/OutletProvider without verifying all three
-   render paths (SSR, navigation, action) produce identical tree structures.
-
-2. Never add or remove wrapper elements (Suspense, div, Fragment) around segment
-   content without checking that the same wrappers exist in ALL render paths.
-
-3. When merging segments (action bridge, partial update), always preserve the
-   cached `loading` value if it differs from the server value. The server may
-   return different `loading` values based on `isSSR` context.
-
-4. Run `pnpm --filter @rangojs/router exec playwright test loader-behavior` after
-   any changes to these files. The skipSSR action tests specifically catch tree
-   structure regressions.

package/src/browser/lru-cache.ts

@@ -1,69 +0,0 @@
-/**
- * Simple LRU (Least Recently Used) cache implementation
- * Used for caching navigation segments to enable instant back/forward
- */
-export class LRUCache<K, V> {
-  private cache = new Map<K, V>();
-  private maxSize: number;
-
-  constructor(maxSize: number) {
-    this.maxSize = maxSize;
-  }
-
-  get(key: K): V | undefined {
-    if (!this.cache.has(key)) {
-      return undefined;
-    }
-
-    // Move to end (most recently used)
-    const value = this.cache.get(key)!;
-    this.cache.delete(key);
-    this.cache.set(key, value);
-    return value;
-  }
-
-  set(key: K, value: V): void {
-    // If key exists, delete it first to update position
-    if (this.cache.has(key)) {
-      this.cache.delete(key);
-    }
-
-    this.cache.set(key, value);
-
-    // Evict oldest entries if over capacity
-    while (this.cache.size > this.maxSize) {
-      const oldestKey = this.cache.keys().next().value;
-      if (oldestKey !== undefined) {
-        this.cache.delete(oldestKey);
-      }
-    }
-  }
-
-  has(key: K): boolean {
-    if (!this.cache.has(key)) {
-      return false;
-    }
-
-    // Move to end (most recently used) - same as get()
-    const value = this.cache.get(key)!;
-    this.cache.delete(key);
-    this.cache.set(key, value);
-    return true;
-  }
-
-  delete(key: K): boolean {
-    return this.cache.delete(key);
-  }
-
-  clear(): void {
-    this.cache.clear();
-  }
-
-  keys(): IterableIterator<K> {
-    return this.cache.keys();
-  }
-
-  get size(): number {
-    return this.cache.size;
-  }
-}

package/src/browser/request-controller.ts

@@ -1,164 +0,0 @@
-import type { RequestController, DisposableAbortController } from "./types.js";
-
-// Polyfill Symbol.dispose for Safari and older browsers
-if (typeof Symbol.dispose === "undefined") {
-  (Symbol as any).dispose = Symbol("Symbol.dispose");
-}
-
-/**
- * Create a request controller for managing concurrent abort controllers
- *
- * This utility helps manage concurrent navigation requests by providing
- * a way to abort all pending requests when a new navigation starts.
- *
- * @returns RequestController instance
- *
- * @example
- * ```typescript
- * const controller = createRequestController();
- *
- * // Start a new request
- * const abortController = controller.create();
- * fetch(url, { signal: abortController.signal });
- *
- * // Abort all pending requests (e.g., when starting new navigation)
- * controller.abortAll();
- *
- * // Clean up completed request
- * controller.remove(abortController);
- * ```
- */
-export function createRequestController(): RequestController {
-  // Navigation controllers - aborted on new navigation
-  // Using WeakRef to allow GC if controller is no longer referenced elsewhere
-  const controllers: WeakRef<AbortController>[] = [];
-  // Action controllers - NOT aborted by navigation, only by errors
-  const actionControllers: WeakRef<AbortController>[] = [];
-
-  /**
-   * Remove stale (garbage collected) refs from an array
-   */
-  function pruneStaleRefs(refs: WeakRef<AbortController>[]): void {
-    for (let i = refs.length - 1; i >= 0; i--) {
-      if (!refs[i].deref()) {
-        refs.splice(i, 1);
-      }
-    }
-  }
-
-  return {
-    /**
-     * Create a new abort controller and track it for navigation
-     *
-     * @returns A new AbortController
-     */
-    create(): AbortController {
-      const controller = new AbortController();
-      controllers.push(new WeakRef(controller));
-      console.log(
-        `[Browser] Created abort controller, total: ${controllers.length}`,
-      );
-      return controller;
-    },
-
-    /**
-     * Create a disposable abort controller for navigation use with `using` keyword
-     *
-     * The controller will be automatically removed from tracking when
-     * it goes out of scope, regardless of how the scope is exited.
-     *
-     * @returns A DisposableAbortController
-     *
-     * @example
-     * ```typescript
-     * async function handleNavigation() {
-     *   requestController.abortAll();
-     *   using { controller } = requestController.createDisposable();
-     *   // ... use controller.signal ...
-     *   // controller is automatically removed on scope exit
-     * }
-     * ```
-     */
-    createDisposable(): DisposableAbortController {
-      const controller = this.create();
-      return {
-        controller,
-        [Symbol.dispose]: () => {
-          this.remove(controller);
-        },
-      };
-    },
-
-    /**
-     * Create a disposable abort controller for actions
-     *
-     * Action controllers are NOT aborted by navigation - they complete
-     * independently. Only aborted by abortAllActions() on error.
-     *
-     * @returns A DisposableAbortController
-     */
-    createActionDisposable(): DisposableAbortController {
-      const controller = new AbortController();
-      const ref = new WeakRef(controller);
-      actionControllers.push(ref);
-      console.log(
-        `[Browser] Created action controller, total: ${actionControllers.length}`,
-      );
-      return {
-        controller,
-        [Symbol.dispose]: () => {
-          const index = actionControllers.indexOf(ref);
-          if (index !== -1) {
-            actionControllers.splice(index, 1);
-            console.log(
-              `[Browser] Removed action controller, remaining: ${actionControllers.length}`,
-            );
-          }
-        },
-      };
-    },
-
-    /**
-     * Abort all navigation controllers (NOT actions)
-     *
-     * Called when starting new navigation. Actions continue
-     * to complete in the background.
-     */
-    abortAll(): void {
-      controllers.forEach((ref) => ref.deref()?.abort());
-      controllers.length = 0;
-      console.log(`[Browser] Aborted all navigation controllers`);
-    },
-
-    /**
-     * Abort all action controllers
-     *
-     * Called when an action error occurs - prevents other actions
-     * from completing and overwriting the error UI.
-     */
-    abortAllActions(): void {
-      actionControllers.forEach((ref) => ref.deref()?.abort());
-      actionControllers.length = 0;
-      console.log(`[Browser] Aborted all action controllers`);
-    },
-
-    /**
-     * Remove a specific controller from tracking
-     *
-     * Call this when a request completes successfully.
-     *
-     * @param controller - The controller to remove
-     */
-    remove(controller: AbortController): void {
-      // Prune any stale refs while searching
-      pruneStaleRefs(controllers);
-      const index = controllers.findIndex((ref) => ref.deref() === controller);
-      if (index !== -1) {
-        controllers.splice(index, 1);
-        console.log(
-          `[Browser] Removed abort controller, remaining: ${controllers.length}`,
-        );
-      }
-    },
-  };
-}

package/src/cache/memory-store.ts

@@ -1,253 +0,0 @@
-/**
- * In-Memory Cache Store
- *
- * Simple implementation for development and testing.
- * Not suitable for production (no persistence, single-instance only).
- *
- * @internal This is reserved for future extensibility.
- * For segment caching, use MemorySegmentCacheStore instead.
- */
-
-import type {
-  CacheStore,
-  CacheEntry,
-  CacheValue,
-  CachePutOptions,
-  CacheMetadata,
-  CacheValueType,
-} from "./types.js";
-
-// ============================================================================
-// Constants
-// ============================================================================
-
-/** Default TTL when no explicit value is provided */
-const DEFAULT_TTL_SECONDS = 60;
-
-// ============================================================================
-// Types
-// ============================================================================
-
-interface StoredEntry {
-  /** Stored value (streams/responses converted to ArrayBuffer) */
-  value: ArrayBuffer | string | object;
-  metadata: CacheMetadata;
-}
-
-/**
- * In-memory cache store implementation
- */
-export class MemoryCacheStore implements CacheStore {
-  private cache = new Map<string, StoredEntry>();
-
-  async match<T = CacheValue>(key: string): Promise<CacheEntry<T> | undefined> {
-    const entry = this.cache.get(key);
-
-    if (!entry) {
-      return undefined;
-    }
-
-    // Check expiration
-    if (entry.metadata.expiresAt && Date.now() > entry.metadata.expiresAt) {
-      this.cache.delete(key);
-      return undefined;
-    }
-
-    // Reconstruct value based on original type
-    const value = this.reconstructValue(entry);
-
-    return {
-      value: value as T,
-      metadata: entry.metadata,
-    };
-  }
-
-  async put<T extends CacheValue>(
-    key: string,
-    value: T,
-    options?: CachePutOptions
-  ): Promise<void> {
-    const ttl = options?.ttl ?? DEFAULT_TTL_SECONDS;
-    const expiresAt = Date.now() + ttl * 1000;
-
-    // Detect value type and convert for storage
-    const { storedValue, valueType, responseHeaders, responseStatus } =
-      await this.prepareForStorage(value);
-
-    const metadata: CacheMetadata = {
-      ...options?.metadata,
-      expiresAt,
-      valueType,
-      responseHeaders,
-      responseStatus,
-    };
-
-    this.cache.set(key, {
-      value: storedValue,
-      metadata,
-    });
-  }
-
-  async delete(key: string): Promise<boolean> {
-    return this.cache.delete(key);
-  }
-
-  /**
-   * Clear all entries (useful for testing)
-   */
-  clear(): void {
-    this.cache.clear();
-  }
-
-  /**
-   * Get current cache size (useful for testing/debugging)
-   */
-  get size(): number {
-    return this.cache.size;
-  }
-
-  /**
-   * Manually purge expired entries
-   */
-  purgeExpired(): number {
-    const now = Date.now();
-    let purged = 0;
-
-    for (const [key, entry] of this.cache) {
-      if (entry.metadata.expiresAt && now > entry.metadata.expiresAt) {
-        this.cache.delete(key);
-        purged++;
-      }
-    }
-
-    return purged;
-  }
-
-  /**
-   * Prepare a value for storage
-   * Converts streams and responses to ArrayBuffer, detects type
-   */
-  private async prepareForStorage(value: CacheValue): Promise<{
-    storedValue: ArrayBuffer | string | object;
-    valueType: CacheValueType;
-    responseHeaders?: Record<string, string>;
-    responseStatus?: number;
-  }> {
-    // ReadableStream -> ArrayBuffer
-    if (value instanceof ReadableStream) {
-      return {
-        storedValue: await streamToArrayBuffer(value),
-        valueType: "stream",
-      };
-    }
-
-    // Response -> ArrayBuffer + headers/status
-    if (value instanceof Response) {
-      const headers: Record<string, string> = {};
-      value.headers.forEach((v, k) => {
-        headers[k] = v;
-      });
-
-      return {
-        storedValue: await value.clone().arrayBuffer(),
-        valueType: "response",
-        responseHeaders: headers,
-        responseStatus: value.status,
-      };
-    }
-
-    // ArrayBuffer -> store as-is
-    if (value instanceof ArrayBuffer) {
-      return {
-        storedValue: value,
-        valueType: "arraybuffer",
-      };
-    }
-
-    // String -> store as-is
-    if (typeof value === "string") {
-      return {
-        storedValue: value,
-        valueType: "string",
-      };
-    }
-
-    // Object -> store as-is (JSON-serializable)
-    return {
-      storedValue: value,
-      valueType: "object",
-    };
-  }
-
-  /**
-   * Reconstruct original value type from stored entry
-   */
-  private reconstructValue(entry: StoredEntry): CacheValue {
-    const { value, metadata } = entry;
-
-    switch (metadata.valueType) {
-      case "stream":
-        return arrayBufferToStream(value as ArrayBuffer);
-
-      case "response": {
-        const status = metadata.responseStatus ?? 200;
-        // Status codes 204 (No Content) and 304 (Not Modified) cannot have a body
-        const isNullBodyStatus = status === 204 || status === 304;
-        return new Response(isNullBodyStatus ? null : (value as ArrayBuffer), {
-          status,
-          headers: metadata.responseHeaders,
-        });
-      }
-
-      case "arraybuffer":
-      case "string":
-      case "object":
-      default:
-        return value as CacheValue;
-    }
-  }
-}
-
-/**
- * Convert a ReadableStream to ArrayBuffer.
- * @internal
- */
-async function streamToArrayBuffer(
-  stream: ReadableStream<Uint8Array>
-): Promise<ArrayBuffer> {
-  const chunks: Uint8Array[] = [];
-  const reader = stream.getReader();
-
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    chunks.push(value);
-  }
-
-  // Concatenate chunks
-  const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
-  const result = new Uint8Array(totalLength);
-  let offset = 0;
-
-  for (const chunk of chunks) {
-    result.set(chunk, offset);
-    offset += chunk.length;
-  }
-
-  return result.buffer;
-}
-
-/**
- * Convert an ArrayBuffer to a ReadableStream.
- * @internal
- */
-function arrayBufferToStream(buffer: ArrayBuffer): ReadableStream<Uint8Array> {
-  const uint8 = new Uint8Array(buffer);
-
-  return new ReadableStream({
-    start(controller) {
-      controller.enqueue(uint8);
-      controller.close();
-    },
-  });
-}

package/src/router.gen.ts

@@ -1,6 +0,0 @@
-// Auto-generated by @rangojs/router - do not edit
-export const routes = {
-  about: "/about",
-  home: "/",
-} as const;
-export type routes = typeof routes;