@rangojs/router 0.0.0-experimental.29 → 0.0.0-experimental.2c0cb8a1

package/AGENTS.md

@@ -3,3 +3,7 @@
 A file-system based React Server Components router.
 
 Run `/rango` to understand the API. Detailed guides for each feature are in the `skills/` directory (e.g. `node_modules/@rangojs/router/skills/loader`, `skills/caching`, `skills/middleware`, etc.).
+
+## Development rules
+
+- Always commit generated files (e.g. `*.gen.ts`) alongside the source changes that produced them.

package/README.md

@@ -10,6 +10,7 @@ Named-route RSC router with structural composability and type-safe partial rende
 - **Structural composability** — Attach routes, loaders, middleware, handles, caching, prerendering, and static generation without hiding the route tree
 - **Composable URL patterns** — Django-style `urls()` DSL with `path`, `layout`, `include`
 - **Data loaders** — `createLoader()` with automatic streaming and Suspense integration
+- **Server actions** — `"use server"` mutations with `useActionState`, `useOptimistic`, and per-segment + per-loader `revalidate()` rules
 - **Live data layer** — Pre-render or cache the UI shell while loaders stay live by default at request time
 - **Layouts & nesting** — Nested layouts with `<Outlet />` and parallel routes
 - **Segment-level caching** — `cache()` DSL with TTL/SWR and pluggable cache stores
@@ -91,24 +92,29 @@ This file is a server/RSC module and should import router construction APIs from
 
 ```tsx
 // src/router.tsx
-import { createRouter, urls } from "@rangojs/router";
-import { Document } from "./document";
+import { createRouter } from "@rangojs/router";
 
-const blogPatterns = urls(({ path }) => [
-  path("/", BlogIndexPage, { name: "index" }),
-  path("/:slug", BlogPostPage, { name: "post" }),
+export const router = createRouter().routes(({ path }) => [
+  path("/", HomePage, { name: "home" }),
+  path("/about", AboutPage, { name: "about" }),
 ]);
 
+export const reverse = router.reverse;
+// reverse("home") -> "/"
+```
+
+For larger apps, extract route modules with `urls()` and compose with `include()`:
+
+```tsx
+import { createRouter, urls } from "@rangojs/router";
+import { blogPatterns } from "./urls/blog";
+
 const urlpatterns = urls(({ path, include }) => [
   path("/", HomePage, { name: "home" }),
   include("/blog", blogPatterns, { name: "blog" }),
 ]);
 
-export const router = createRouter({ document: Document }).routes(urlpatterns);
-
-// Export typed reverse function for URL generation by route name
-export const reverse = router.reverse;
-
+export const router = createRouter().routes(urlpatterns);
 // reverse("blog.post", { slug: "hello-world" }) -> "/blog/hello-world"
 ```
 
@@ -156,13 +162,18 @@ const urlpatterns = urls(({ path }) => [
 ]);
 ```
 
-Use `reverse()` as the default way to link to routes:
+Use `ctx.reverse()` from handler context as the default way to link to routes from server code:
 
 ```tsx
-router.reverse("product", { slug: "widget" }); // "/product/widget"
-router.reverse("search", undefined, { q: "rsc" }); // "/search?q=rsc"
+const ProductPage: Handler<"product"> = (ctx) => {
+  const url = ctx.reverse("product", { slug: "widget" }); // "/product/widget"
+  const searchUrl = ctx.reverse("search", undefined, { q: "rsc" }); // "/search?q=rsc"
+  return <Link to={url}>Widget</Link>;
+};
 ```
 
+`router.reverse()` (exported from the router module) is the same function without a handler context, useful in scripts or tests. In request code, prefer `ctx.reverse()` — it auto-fills mount params from the current match.
+
 ### Composable URL Modules
 
 Local route names compose cleanly with `include(..., { name })`:
@@ -275,7 +286,8 @@ All handler typing styles are supported, but they solve different problems:
 Example of a scoped local name inside a mounted module:
 
 ```tsx
-import type { Handler, ScopedRouteMap } from "@rangojs/router";
+import type { Handler } from "@rangojs/router";
+import type { ScopedRouteMap } from "@rangojs/router/__internal";
 
 type BlogRoutes = ScopedRouteMap<"blog">;
 
@@ -471,41 +483,130 @@ const urlpatterns = urls(({ path, loader }) => [
 ]);
 ```
 
-## Navigation & Links
+## Server Actions
 
-### Named Routes with `reverse()` (Server Components)
+Server actions are React's RSC mutation primitive. Define them with the
+`"use server"` directive — Rango uses standard React 19 hooks
+(`useActionState`, `useFormStatus`, `useOptimistic`) with no framework wrapper.
 
-In server components, use `reverse()` to generate URLs by route name:
+```tsx
+// app/actions/cart.ts
+"use server";
+
+import { getRequestContext } from "@rangojs/router";
+
+export async function addToCart(productId: string): Promise<void> {
+  const ctx = getRequestContext();
+  const userId = ctx.get("user").id;
+  await db.cart.insert({ userId, productId });
+}
+```
 
 ```tsx
-import { Link } from "@rangojs/router/client";
-import { reverse } from "./router";
+// Client form with progressive enhancement + pending state
+"use client";
+import { useActionState } from "react";
+import { saveProfile } from "../actions/profile";
 
-function BlogIndex() {
+export function ProfileForm() {
+  const [state, action, pending] = useActionState(saveProfile, null);
   return (
-    <nav>
-      <Link to={reverse("home")}>Home</Link>
-      <Link to={reverse("blogPost", { slug: "my-post" })}>My Post</Link>
-      <Link to={reverse("about")}>About</Link>
-    </nav>
+    <form action={action}>
+      <input name="name" defaultValue={state?.values?.name} />
+      {state?.errors?.name && <p role="alert">{state.errors.name}</p>}
+      <button disabled={pending}>{pending ? "Saving…" : "Save"}</button>
+    </form>
   );
 }
 ```
 
-`reverse()` is type-safe — route names and required params are checked at compile time. Included routes use dotted names: `reverse("api.health")`.
+After an action runs, matched route segments (path/layout/parallel/intercept)
+and loaders can re-render/re-resolve so the UI reflects the new state.
+Attach a `revalidate(({ actionId }) => ...)` rule on any segment or loader
+that owns data the action touched:
+
+```tsx
+urls(({ path, loader, revalidate }) => [
+  // Segment-level: re-render the cart page handler after cart actions.
+  // Nest loaders that belong to this route inside the same path() so the
+  // segment owns its data dependencies.
+  path("/cart", CartPage, { name: "cart" }, () => [
+    revalidate(
+      ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
+    ),
+    loader(CartLoader, () => [
+      revalidate(
+        ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
+      ),
+    ]),
+  ]),
+]);
+```
+
+For the full guide — validation with Zod, error handling, file uploads,
+`useOptimistic`, redirects, and progressive enhancement — see the
+`/server-actions` skill.
+
+## Navigation & Links
 
-Handlers also have `ctx.reverse()` directly on the context:
+### Named Routes with `ctx.reverse()` (Server)
+
+In server components and handlers, use `ctx.reverse()` to generate URLs by route name. This is the default — it is typed, auto-fills mount params from the current match, and resolves both local (`.name`) and absolute (`name.sub`) names:
 
 ```tsx
+import { Link } from "@rangojs/router/client";
+import type { Handler } from "@rangojs/router";
+
 const BlogPostPage: Handler<"blogPost"> = (ctx) => {
   const backUrl = ctx.reverse("blog");
   return <Link to={backUrl}>Back to blog</Link>;
 };
 ```
 
+`reverse()` is type-safe — route names and required params are checked at compile time. Included routes use dotted names: `ctx.reverse("api.health")`.
+
+For scripts, tests, or other code without a handler context, import the router-level `reverse`:
+
+```tsx
+import { reverse } from "./router";
+reverse("blogPost", { slug: "my-post" });
+```
+
+### Client Components
+
+**`reverse()` is server-only.** It depends on the route manifest and handler context — neither is available in the browser bundle. Client components receive URLs as props, loader data, or server-action return values:
+
+```tsx
+// server
+function BlogIndex(ctx: HandlerContext) {
+  return (
+    <Nav
+      home={ctx.reverse("home")}
+      post={ctx.reverse("blogPost", { slug: "my-post" })}
+    />
+  );
+}
+```
+
+```tsx
+"use client";
+import { Link } from "@rangojs/router/client";
+
+export function Nav({ home, post }: { home: string; post: string }) {
+  return (
+    <nav>
+      <Link to={home}>Home</Link>
+      <Link to={post}>My Post</Link>
+    </nav>
+  );
+}
+```
+
+For client-side navigation to static paths (no named-route lookup), use `href()` — see below. For URLs tied to named routes, you have two options: import the per-module generated `routes` map and use `useReverse(routes)` for in-module names (see [`/links` skill](./skills/links/SKILL.md)), or generate the URL on the server and pass the string in for cross-module URLs.
+
 ### `href()` for Path Validation (Client Components)
 
-In client components, use `href()` for compile-time path validation:
+In client components, use `href()` for compile-time path validation on static path strings:
 
 ```tsx
 "use client";
@@ -710,10 +811,12 @@ export const BlogPost = Prerender(
 
 ### Passthrough for Unknown Params
 
+Wrap a `Prerender` definition with `Passthrough()` to add a live handler for unknown params at runtime. The build handler runs at build time, the live handler runs at request time for params not in the prerender cache.
+
 ```tsx
-import { Prerender } from "@rangojs/router";
+import { Prerender, Passthrough } from "@rangojs/router";
 
-export const ProductPage = Prerender(
+export const ProductPageDef = Prerender(
   async () => {
     const featured = await db.getFeaturedProducts();
     return featured.map((p) => ({ id: p.id }));
@@ -722,16 +825,22 @@ export const ProductPage = Prerender(
     const product = await db.getProduct(ctx.params.id);
     return <Product data={product} />;
   },
-  { passthrough: true },
 );
-```
 
-With `passthrough: true`, known params are served from the build-time cache and unknown params fall through to live rendering.
+// In route definition:
+path(
+  "/products/:id",
+  Passthrough(ProductPageDef, async (ctx) => {
+    const product = await ctx.env.DB.getProduct(ctx.params.id);
+    return <Product data={product} />;
+  }),
+);
+```
 
-Handlers can also skip individual param sets with `ctx.passthrough()`, deferring them to the live handler at runtime:
+Build handlers can also skip individual param sets with `ctx.passthrough()`, deferring them to the live handler:
 
 ```tsx
-export const ProductPage = Prerender(
+export const ProductPageDef = Prerender(
   async () => {
     const all = await db.getAllProducts();
     return all.map((p) => ({ id: p.id }));
@@ -741,10 +850,55 @@ export const ProductPage = Prerender(
     if (!product.published) return ctx.passthrough();
     return <Product data={product} />;
   },
-  { passthrough: true },
 );
 ```
 
+### Build-Time Environment Bindings
+
+Prerender handlers can access platform bindings (KV, D1, R2) at build time when `buildEnv` is configured in the Vite plugin:
+
+```ts
+// vite.config.ts
+import { rango } from "@rangojs/router/vite";
+
+rango({ preset: "cloudflare", buildEnv: "auto" });
+```
+
+With `buildEnv: "auto"`, the plugin calls `wrangler.getPlatformProxy()` to provide local bindings. Handlers then access `ctx.env` during build:
+
+```tsx
+export const BlogPosts = Prerender<{ slug: string }>(
+  async (ctx) => {
+    const rows = await ctx.env.DB.prepare("SELECT slug FROM posts").all();
+    return rows.map((r) => ({ slug: r.slug }));
+  },
+  async (ctx) => {
+    const post = await ctx.env.DB.prepare("SELECT * FROM posts WHERE slug = ?")
+      .bind(ctx.params.slug)
+      .first();
+    return <BlogPost post={post} />;
+  },
+);
+```
+
+`buildEnv` also accepts a factory function or plain object:
+
+```ts
+// Custom factory
+rango({
+  buildEnv: async (ctx) => {
+    const { getPlatformProxy } = await import("wrangler");
+    const proxy = await getPlatformProxy();
+    return { env: proxy.env, dispose: proxy.dispose };
+  },
+});
+
+// Plain object (Node.js)
+rango({ buildEnv: { DATABASE_URL: process.env.DATABASE_URL } });
+```
+
+Build-time env applies to both production builds and dev on-demand prerender. Without `buildEnv`, accessing `ctx.env` in a Prerender handler throws with a clear error.
+
 ## Theme
 
 ### Router Configuration

package/dist/__internal.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Internal Types - Implementation Details
+ *
+ * @internal
+ * These types are for internal use only and should not be relied upon by consumers.
+ * They may change without notice between versions.
+ *
+ * If you find yourself needing these types, please open an issue to discuss
+ * adding them to the public API.
+ */
+/**
+ * @internal
+ * Internal representation of a resolved route segment.
+ * Used during route matching and rendering pipeline.
+ */
+export type { ResolvedSegment, SegmentMetadata } from "./types.js";
+/**
+ * @internal
+ * Internal match result from route resolution.
+ */
+export type { MatchResult, SlotState } from "./types.js";
+/**
+ * @internal
+ * Context for intercept route selection.
+ */
+export type { InterceptSelectorContext, InterceptSegmentsState, InterceptWhenFn, } from "./server/context.js";
+/**
+ * @internal
+ * RSC protocol payload structure.
+ */
+export type { RscPayload, ReactFormState } from "./rsc/types.js";
+/**
+ * @internal
+ * Internal navigation store interface.
+ */
+export type { NavigationStore, NavigationBridge, RscMetadata, ActionResult, InflightAction, NavigationState, TrackedActionState, ActionStateListener, SegmentCache, SegmentState, NavigationUpdate, } from "./browser/types.js";
+/**
+ * @internal
+ * Internal handle storage mechanism.
+ */
+export type { HandleStore, HandleData } from "./server/handle-store.js";
+/**
+ * @internal
+ * Segment handle data in cache.
+ */
+export type { SegmentHandleData } from "./cache/types.js";
+/**
+ * @internal
+ * Internal cache entry data structure.
+ */
+export type { CachedEntryData, CachedEntryResult, CacheGetResult, SerializedSegmentData, CacheDefaults, } from "./cache/types.js";
+/**
+ * @internal
+ * Router context for AsyncLocalStorage.
+ */
+export type { RouterContext, RevalidationContext, InterceptResult } from "./router/router-context.js";
+/**
+ * @internal
+ * Route match context during pipeline processing.
+ */
+export type { MatchContext, MatchPipelineState } from "./router/match-context.js";
+/**
+ * @internal
+ * Pattern matching result.
+ */
+export type { RouteMatchResult } from "./router/pattern-matching.js";
+/**
+ * @internal
+ * Entry data during route traversal.
+ */
+export type { EntryData, InterceptEntry, MetricsStore, PerformanceMetric, EntryCacheConfig, EntryPropCommon, EntryPropDatas, LoaderEntry, EntryPropSegments, } from "./server/context.js";
+/**
+ * @internal
+ * Internal handler context with additional props for router internals.
+ * Includes `_originalRequest` and `_currentSegmentId`.
+ */
+export type { InternalHandlerContext } from "./types.js";
+/**
+ * @internal
+ * Debug utilities for manifest inspection and comparison.
+ */
+export { serializeManifest, compareManifests, formatManifestDiff, type SerializedEntry, type SerializedManifest, } from "./debug.js";
+//# sourceMappingURL=__internal.d.ts.map

package/dist/__internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__internal.d.ts","sourceRoot":"","sources":["../src/__internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;GAIG;AACH,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEnE;;;GAGG;AACH,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAMzD;;;GAGG;AACH,YAAY,EACV,wBAAwB,EACxB,sBAAsB,EACtB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAM7B;;;GAGG;AACH,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEjE;;;GAGG;AACH,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAM5B;;;GAGG;AACH,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAExE;;;GAGG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAM1D;;;GAGG;AACH,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACrB,aAAa,GACd,MAAM,kBAAkB,CAAC;AAM1B;;;GAGG;AACH,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAMtG;;;GAGG;AACH,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAElF;;;GAGG;AACH,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAMrE;;;GAGG;AACH,YAAY,EACV,SAAS,EACT,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,WAAW,EACX,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAM7B;;;;GAIG;AACH,YAAY,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAMzD;;;GAGG;AACH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC"}

package/dist/__internal.js

@@ -0,0 +1,19 @@
+/**
+ * Internal Types - Implementation Details
+ *
+ * @internal
+ * These types are for internal use only and should not be relied upon by consumers.
+ * They may change without notice between versions.
+ *
+ * If you find yourself needing these types, please open an issue to discuss
+ * adding them to the public API.
+ */
+// ============================================================================
+// Debug Utilities (Internal)
+// ============================================================================
+/**
+ * @internal
+ * Debug utilities for manifest inspection and comparison.
+ */
+export { serializeManifest, compareManifests, formatManifestDiff, } from "./debug.js";
+//# sourceMappingURL=__internal.js.map

package/dist/__internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"__internal.js","sourceRoot":"","sources":["../src/__internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAsJH,+EAA+E;AAC/E,6BAA6B;AAC7B,+EAA+E;AAE/E;;;GAGG;AACH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,GAGnB,MAAM,YAAY,CAAC"}

package/dist/__mocks__/version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Mock for rsc-router:version virtual module.
+ * Used by vitest since the virtual module is only available at build time.
+ * Empty string disables version path in URLs for simpler test assertions.
+ */
+export declare const VERSION = "";
+//# sourceMappingURL=version.d.ts.map

package/dist/__mocks__/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/__mocks__/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,OAAO,KAAK,CAAC"}

package/dist/__mocks__/version.js

@@ -0,0 +1,7 @@
+/**
+ * Mock for rsc-router:version virtual module.
+ * Used by vitest since the virtual module is only available at build time.
+ * Empty string disables version path in URLs for simpler test assertions.
+ */
+export const VERSION = "";
+//# sourceMappingURL=version.js.map

package/dist/__mocks__/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/__mocks__/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,EAAE,CAAC"}

package/dist/__tests__/client-href.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client-href.test.d.ts.map

package/dist/__tests__/client-href.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-href.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/client-href.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/client-href.test.js

@@ -0,0 +1,74 @@
+import { describe, it, expect, expectTypeOf } from "vitest";
+import { href } from "../href-client.js";
+describe("href()", () => {
+    describe("without mount", () => {
+        it("returns path unchanged", () => {
+            expect(href("/foo")).toBe("/foo");
+        });
+        it("handles root path", () => {
+            expect(href("/")).toBe("/");
+        });
+        it("handles nested paths", () => {
+            expect(href("/blog/my-post")).toBe("/blog/my-post");
+        });
+        it("handles paths with query strings", () => {
+            expect(href("/search?q=test")).toBe("/search?q=test");
+        });
+        it("handles paths with hash fragments", () => {
+            expect(href("/about#contact")).toBe("/about#contact");
+        });
+        it("handles paths with query and hash", () => {
+            expect(href("/page?a=1#top")).toBe("/page?a=1#top");
+        });
+    });
+    describe("with mount", () => {
+        it("prepends mount to path", () => {
+            expect(href("/foo", "/articles")).toBe("/articles/foo");
+        });
+        it("prepends mount to root path", () => {
+            expect(href("/", "/articles")).toBe("/articles/");
+        });
+        it("handles nested mount", () => {
+            expect(href("/detail", "/articles/comments")).toBe("/articles/comments/detail");
+        });
+        it("treats root mount as no mount", () => {
+            expect(href("/foo", "/")).toBe("/foo");
+        });
+        it("handles undefined mount", () => {
+            expect(href("/foo", undefined)).toBe("/foo");
+        });
+        it("handles empty string mount", () => {
+            expect(href("/foo", "")).toBe("/foo");
+        });
+    });
+    describe("PatternToPath types", () => {
+        it("static path", () => {
+            expectTypeOf().toEqualTypeOf();
+        });
+        it("dynamic param", () => {
+            expectTypeOf().toEqualTypeOf();
+        });
+        it("optional param at end", () => {
+            expectTypeOf().toEqualTypeOf();
+        });
+        it("constrained param", () => {
+            expectTypeOf().toEqualTypeOf();
+        });
+        it("multiple dynamic params", () => {
+            expectTypeOf().toEqualTypeOf();
+        });
+        it("root path stays root", () => {
+            expectTypeOf().toEqualTypeOf();
+        });
+    });
+    describe("ValidPaths fallback", () => {
+        // When no routes are registered, ValidPaths falls back to `/${string}`
+        // This is tested implicitly by the fact that href() accepts any path starting with /
+        it("accepts any path when no routes registered", () => {
+            // href() is callable with any /-prefixed string
+            const result = href("/anything/at/all");
+            expect(result).toBe("/anything/at/all");
+        });
+    });
+});
+//# sourceMappingURL=client-href.test.js.map

package/dist/__tests__/client-href.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-href.test.js","sourceRoot":"","sources":["../../src/__tests__/client-href.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/component-utils.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=component-utils.test.d.ts.map

package/dist/__tests__/component-utils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-utils.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/component-utils.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/component-utils.test.js

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { isClientComponent, assertClientComponent } from "../component-utils";
+describe("component-utils", () => {
+    describe("isClientComponent", () => {
+        it("should return false for regular functions", () => {
+            const ServerComponent = () => null;
+            expect(isClientComponent(ServerComponent)).toBe(false);
+        });
+        it("should return false for non-functions", () => {
+            expect(isClientComponent(null)).toBe(false);
+            expect(isClientComponent(undefined)).toBe(false);
+            expect(isClientComponent("string")).toBe(false);
+            expect(isClientComponent(123)).toBe(false);
+            expect(isClientComponent({})).toBe(false);
+        });
+        it("should return true for functions with client reference marker", () => {
+            const ClientComponent = () => null;
+            // Simulate what the bundler does for "use client" components
+            ClientComponent.$$typeof = Symbol.for("react.client.reference");
+            ClientComponent.$$id = "src/components/MyComponent.tsx#default";
+            expect(isClientComponent(ClientComponent)).toBe(true);
+        });
+        it("should return false for functions with wrong $$typeof symbol", () => {
+            const Component = () => null;
+            Component.$$typeof = Symbol.for("react.element");
+            expect(isClientComponent(Component)).toBe(false);
+        });
+    });
+    describe("assertClientComponent", () => {
+        it("should throw for non-function values", () => {
+            expect(() => assertClientComponent(null, "document")).toThrow('document must be a client component function with "use client" directive');
+            expect(() => assertClientComponent({}, "document")).toThrow('document must be a client component function with "use client" directive');
+        });
+        it("should throw for server components (no client marker)", () => {
+            const ServerComponent = () => null;
+            expect(() => assertClientComponent(ServerComponent, "document")).toThrow('document must be a client component with "use client" directive');
+            expect(() => assertClientComponent(ServerComponent, "document")).toThrow("cannot be serialized in the RSC payload");
+        });
+        it("should not throw for client components", () => {
+            const ClientComponent = () => null;
+            ClientComponent.$$typeof = Symbol.for("react.client.reference");
+            ClientComponent.$$id = "src/document.tsx#default";
+            expect(() => assertClientComponent(ClientComponent, "document")).not.toThrow();
+        });
+        it("should include component name in error message", () => {
+            const ServerComponent = () => null;
+            expect(() => assertClientComponent(ServerComponent, "myLayout")).toThrow("myLayout must be a client component");
+        });
+    });
+});
+//# sourceMappingURL=component-utils.test.js.map

package/dist/__tests__/component-utils.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-utils.test.js","sourceRoot":"","sources":["../../src/__tests__/component-utils.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/event-controller.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=event-controller.test.d.ts.map

package/dist/__tests__/event-controller.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-controller.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/event-controller.test.ts"],"names":[],"mappings":""}