npm - @rangojs/router - Versions diffs - 0.0.0-experimental.10 - Mend

@rangojs/router 0.0.0-experimental.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (172) hide show

package/CLAUDE.md +43 -0
package/README.md +19 -0
package/dist/bin/rango.js +227 -0
package/dist/vite/index.js +3039 -0
package/package.json +171 -0
package/skills/caching/SKILL.md +191 -0
package/skills/debug-manifest/SKILL.md +108 -0
package/skills/document-cache/SKILL.md +180 -0
package/skills/fonts/SKILL.md +165 -0
package/skills/hooks/SKILL.md +442 -0
package/skills/intercept/SKILL.md +190 -0
package/skills/layout/SKILL.md +213 -0
package/skills/links/SKILL.md +180 -0
package/skills/loader/SKILL.md +246 -0
package/skills/middleware/SKILL.md +202 -0
package/skills/mime-routes/SKILL.md +124 -0
package/skills/parallel/SKILL.md +228 -0
package/skills/prerender/SKILL.md +283 -0
package/skills/rango/SKILL.md +54 -0
package/skills/response-routes/SKILL.md +358 -0
package/skills/route/SKILL.md +173 -0
package/skills/router-setup/SKILL.md +346 -0
package/skills/tailwind/SKILL.md +129 -0
package/skills/theme/SKILL.md +78 -0
package/skills/typesafety/SKILL.md +394 -0
package/src/__internal.ts +175 -0
package/src/bin/rango.ts +24 -0
package/src/browser/event-controller.ts +876 -0
package/src/browser/index.ts +18 -0
package/src/browser/link-interceptor.ts +121 -0
package/src/browser/lru-cache.ts +69 -0
package/src/browser/merge-segment-loaders.ts +126 -0
package/src/browser/navigation-bridge.ts +913 -0
package/src/browser/navigation-client.ts +165 -0
package/src/browser/navigation-store.ts +823 -0
package/src/browser/partial-update.ts +600 -0
package/src/browser/react/Link.tsx +248 -0
package/src/browser/react/NavigationProvider.tsx +346 -0
package/src/browser/react/ScrollRestoration.tsx +94 -0
package/src/browser/react/context.ts +53 -0
package/src/browser/react/index.ts +52 -0
package/src/browser/react/location-state-shared.ts +120 -0
package/src/browser/react/location-state.ts +62 -0
package/src/browser/react/mount-context.ts +32 -0
package/src/browser/react/use-action.ts +240 -0
package/src/browser/react/use-client-cache.ts +56 -0
package/src/browser/react/use-handle.ts +203 -0
package/src/browser/react/use-href.tsx +40 -0
package/src/browser/react/use-link-status.ts +134 -0
package/src/browser/react/use-mount.ts +31 -0
package/src/browser/react/use-navigation.ts +140 -0
package/src/browser/react/use-segments.ts +188 -0
package/src/browser/request-controller.ts +164 -0
package/src/browser/rsc-router.tsx +352 -0
package/src/browser/scroll-restoration.ts +324 -0
package/src/browser/segment-structure-assert.ts +67 -0
package/src/browser/server-action-bridge.ts +762 -0
package/src/browser/shallow.ts +35 -0
package/src/browser/types.ts +478 -0
package/src/build/generate-manifest.ts +377 -0
package/src/build/generate-route-types.ts +828 -0
package/src/build/index.ts +36 -0
package/src/build/route-trie.ts +239 -0
package/src/cache/cache-scope.ts +563 -0
package/src/cache/cf/cf-cache-store.ts +428 -0
package/src/cache/cf/index.ts +19 -0
package/src/cache/document-cache.ts +340 -0
package/src/cache/index.ts +58 -0
package/src/cache/memory-segment-store.ts +150 -0
package/src/cache/memory-store.ts +253 -0
package/src/cache/types.ts +392 -0
package/src/client.rsc.tsx +83 -0
package/src/client.tsx +643 -0
package/src/component-utils.ts +76 -0
package/src/components/DefaultDocument.tsx +23 -0
package/src/debug.ts +233 -0
package/src/default-error-boundary.tsx +88 -0
package/src/deps/browser.ts +8 -0
package/src/deps/html-stream-client.ts +2 -0
package/src/deps/html-stream-server.ts +2 -0
package/src/deps/rsc.ts +10 -0
package/src/deps/ssr.ts +2 -0
package/src/errors.ts +295 -0
package/src/handle.ts +130 -0
package/src/handles/MetaTags.tsx +193 -0
package/src/handles/index.ts +6 -0
package/src/handles/meta.ts +247 -0
package/src/host/cookie-handler.ts +159 -0
package/src/host/errors.ts +97 -0
package/src/host/index.ts +56 -0
package/src/host/pattern-matcher.ts +214 -0
package/src/host/router.ts +330 -0
package/src/host/testing.ts +79 -0
package/src/host/types.ts +138 -0
package/src/host/utils.ts +25 -0
package/src/href-client.ts +202 -0
package/src/href-context.ts +33 -0
package/src/index.rsc.ts +121 -0
package/src/index.ts +165 -0
package/src/loader.rsc.ts +207 -0
package/src/loader.ts +47 -0
package/src/network-error-thrower.tsx +21 -0
package/src/outlet-context.ts +15 -0
package/src/prerender/param-hash.ts +35 -0
package/src/prerender/store.ts +40 -0
package/src/prerender.ts +156 -0
package/src/reverse.ts +267 -0
package/src/root-error-boundary.tsx +277 -0
package/src/route-content-wrapper.tsx +193 -0
package/src/route-definition.ts +1431 -0
package/src/route-map-builder.ts +242 -0
package/src/route-types.ts +220 -0
package/src/router/error-handling.ts +287 -0
package/src/router/handler-context.ts +158 -0
package/src/router/intercept-resolution.ts +387 -0
package/src/router/loader-resolution.ts +327 -0
package/src/router/manifest.ts +216 -0
package/src/router/match-api.ts +621 -0
package/src/router/match-context.ts +264 -0
package/src/router/match-middleware/background-revalidation.ts +236 -0
package/src/router/match-middleware/cache-lookup.ts +382 -0
package/src/router/match-middleware/cache-store.ts +276 -0
package/src/router/match-middleware/index.ts +81 -0
package/src/router/match-middleware/intercept-resolution.ts +281 -0
package/src/router/match-middleware/segment-resolution.ts +184 -0
package/src/router/match-pipelines.ts +214 -0
package/src/router/match-result.ts +213 -0
package/src/router/metrics.ts +62 -0
package/src/router/middleware.ts +791 -0
package/src/router/pattern-matching.ts +407 -0
package/src/router/revalidation.ts +190 -0
package/src/router/router-context.ts +301 -0
package/src/router/segment-resolution.ts +1315 -0
package/src/router/trie-matching.ts +172 -0
package/src/router/types.ts +163 -0
package/src/router.gen.ts +6 -0
package/src/router.ts +2423 -0
package/src/rsc/handler.ts +1443 -0
package/src/rsc/helpers.ts +64 -0
package/src/rsc/index.ts +56 -0
package/src/rsc/nonce.ts +18 -0
package/src/rsc/types.ts +236 -0
package/src/segment-system.tsx +442 -0
package/src/server/context.ts +466 -0
package/src/server/handle-store.ts +229 -0
package/src/server/loader-registry.ts +174 -0
package/src/server/request-context.ts +554 -0
package/src/server/root-layout.tsx +10 -0
package/src/server/tsconfig.json +14 -0
package/src/server.ts +171 -0
package/src/ssr/index.tsx +296 -0
package/src/theme/ThemeProvider.tsx +291 -0
package/src/theme/ThemeScript.tsx +61 -0
package/src/theme/constants.ts +59 -0
package/src/theme/index.ts +58 -0
package/src/theme/theme-context.ts +70 -0
package/src/theme/theme-script.ts +152 -0
package/src/theme/types.ts +182 -0
package/src/theme/use-theme.ts +44 -0
package/src/types.ts +1757 -0
package/src/urls.gen.ts +8 -0
package/src/urls.ts +1282 -0
package/src/use-loader.tsx +346 -0
package/src/vite/expose-action-id.ts +344 -0
package/src/vite/expose-handle-id.ts +209 -0
package/src/vite/expose-loader-id.ts +426 -0
package/src/vite/expose-location-state-id.ts +177 -0
package/src/vite/expose-prerender-handler-id.ts +429 -0
package/src/vite/index.ts +2068 -0
package/src/vite/package-resolution.ts +125 -0
package/src/vite/version.d.ts +12 -0
package/src/vite/virtual-entries.ts +114 -0

package/skills/fonts/SKILL.md ADDED Viewed

@@ -0,0 +1,165 @@
+---
+name: fonts
+description: Load and configure web fonts with preload hints for optimal performance
+argument-hint: [provider]
+---
+# Fonts
+Load web fonts in the Document component with `<link rel="preload">` for optimal performance. Fonts are declared in `<head>` alongside your stylesheet.
+## Google Fonts
+```tsx
+// src/document.tsx
+"use client";
+import type { ReactNode } from "react";
+import { MetaTags } from "@rangojs/router/client";
+import styles from "./index.css?url";
+export function Document({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        {/* Preconnect to Google Fonts */}
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
+        {/* Load font stylesheet */}
+        <link
+          href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
+          rel="stylesheet"
+        />
+        {/* App styles */}
+        <link rel="preload" href={styles} as="style" />
+        <link rel="stylesheet" href={styles} />
+        <MetaTags />
+      </head>
+      <body>
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+Then reference the font in CSS:
+```css
+/* src/index.css */
+body {
+  font-family: "Inter", sans-serif;
+}
+```
+Or with Tailwind (see `/tailwind`):
+```css
+/* src/index.css */
+@theme {
+  --font-sans: "Inter", sans-serif;
+}
+```
+## Self-Hosted Fonts
+Place font files in `public/fonts/` and use `@font-face`:
+```css
+/* src/index.css */
+@font-face {
+  font-family: "CustomFont";
+  src: url("/fonts/custom-regular.woff2") format("woff2");
+  font-weight: 400;
+  font-style: normal;
+  font-display: swap;
+}
+@font-face {
+  font-family: "CustomFont";
+  src: url("/fonts/custom-bold.woff2") format("woff2");
+  font-weight: 700;
+  font-style: normal;
+  font-display: swap;
+}
+body {
+  font-family: "CustomFont", sans-serif;
+}
+```
+Preload the most critical weight in the Document:
+```tsx
+export function Document({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <link
+          rel="preload"
+          href="/fonts/custom-regular.woff2"
+          as="font"
+          type="font/woff2"
+          crossOrigin="anonymous"
+        />
+        <link rel="preload" href={styles} as="style" />
+        <link rel="stylesheet" href={styles} />
+        <MetaTags />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+## Fontsource (Recommended for Vite)
+`@fontsource-variable` packages are the recommended approach with Vite. Fonts are installed as npm dependencies, bundled by Vite, and served from your own domain -- no external requests, no privacy concerns, no FOUT from slow CDNs.
+```bash
+pnpm add @fontsource-variable/inter
+```
+Import the font CSS in your stylesheet. Vite resolves the `@fontsource-variable` import from `node_modules` and bundles the woff2 files as hashed assets automatically:
+```css
+/* src/index.css */
+@import "@fontsource-variable/inter";
+body {
+  font-family: "Inter Variable", sans-serif;
+}
+```
+With Tailwind:
+```css
+/* src/index.css */
+@import "@fontsource-variable/inter";
+@import "tailwindcss";
+@theme {
+  --font-sans: "Inter Variable", sans-serif;
+}
+```
+Why this is preferred over Google Fonts with Vite:
+- No external network requests at runtime -- fonts are bundled into your build output
+- No `<link rel="preconnect">` or extra stylesheet needed in the Document
+- Variable font = single file covers all weights, smaller total download
+- Vite handles cache-busting via content hashes
+- Works offline and in edge deployments (Cloudflare Workers) without external dependencies
+Browse available fonts at fontsource.org. Use `@fontsource-variable/*` for variable fonts and `@fontsource/*` for static fonts.
+## Performance Tips
+- Prefer `@fontsource-variable` with Vite for self-hosted, zero-config font loading
+- Use `font-display: swap` to prevent invisible text during font load
+- Preload only the most critical font weight (usually regular 400)
+- Prefer `woff2` format for smaller file sizes
+- Use variable fonts when multiple weights are needed to reduce total file count
+- `<link rel="preconnect">` eliminates DNS + TLS latency for external font providers

package/skills/hooks/SKILL.md ADDED Viewed

@@ -0,0 +1,442 @@
+---
+name: hooks
+description: Client-side React hooks for navigation, loaders, and state in @rangojs/router
+argument-hint: [hook-name]
+---
+# Client-Side React Hooks
+All hooks are imported from `@rangojs/router` or `@rangojs/router/client`.
+## Navigation Hooks
+### useNavigation()
+Track navigation state and control navigation:
+```tsx
+"use client";
+import { useNavigation } from "@rangojs/router";
+function NavIndicator() {
+  const nav = useNavigation();
+  // Full state
+  nav.state;        // 'idle' | 'loading' | 'streaming'
+  nav.isStreaming;  // boolean
+  nav.location;     // Current URL
+  nav.pendingUrl;   // Target URL during navigation (or null)
+  // Methods
+  nav.navigate("/products");           // Navigate programmatically
+  nav.navigate("/products", { replace: true }); // Replace history
+  nav.refresh();                       // Refresh current route
+  return nav.state === 'loading' ? <Spinner /> : null;
+}
+// With selector for performance
+function IsLoading() {
+  const isLoading = useNavigation(nav => nav.state === 'loading');
+  return isLoading ? <Spinner /> : null;
+}
+```
+### useSegments()
+Access current URL path and matched route segments:
+```tsx
+"use client";
+import { useSegments } from "@rangojs/router";
+function Breadcrumbs() {
+  const { path, segmentIds, location } = useSegments();
+  // path: ["/shop", "products", "123"]
+  // segmentIds: ["shop-layout", "products-route"]
+  // location: URL object
+  return <nav>{path.join(" > ")}</nav>;
+}
+// With selector
+const isShopRoute = useSegments(s => s.path[0] === "shop");
+```
+### useLinkStatus()
+Track pending state inside a Link component:
+```tsx
+"use client";
+import { Link, useLinkStatus } from "@rangojs/router/client";
+function LoadingIndicator() {
+  const { pending } = useLinkStatus();
+  return pending ? <Spinner /> : null;
+}
+// Must be inside Link
+<Link to="/dashboard">
+  Dashboard
+  <LoadingIndicator />
+</Link>
+```
+## Data Hooks
+### useLoader()
+Access loader data (strict - data guaranteed):
+```tsx
+"use client";
+import { useLoader } from "@rangojs/router";
+import { ProductLoader } from "../loaders/product";
+function ProductPrice() {
+  const { data, isLoading, error } = useLoader(ProductLoader);
+  // data: T (guaranteed - throws if not in context)
+  // isLoading: boolean
+  // error: Error | null
+  return <span>${data.price}</span>;
+}
+```
+**Precondition**: Loader must be registered on route via `loader()` helper.
+Loaders can also be passed as props from server to client components:
+```tsx
+"use client";
+import { useLoader } from "@rangojs/router/client";
+import type { ProductLoader } from "../loaders";
+// typeof infers the full data type from the loader definition
+function ProductCard({ loader }: { loader: typeof ProductLoader }) {
+  const { data } = useLoader(loader);
+  return <h2>{data.product.name}</h2>;
+}
+```
+### useFetchLoader()
+Access loader with on-demand fetching (flexible):
+```tsx
+"use client";
+import { useFetchLoader } from "@rangojs/router";
+import { SearchLoader } from "../loaders/search";
+function SearchResults() {
+  const { data, load, isLoading, error } = useFetchLoader(SearchLoader);
+  // data: T | undefined (may be undefined if not fetched)
+  // load: (options?) => Promise<T>
+  // refetch: alias for load
+  const handleSearch = async (query: string) => {
+    await load({ params: { query } });
+  };
+  return (
+    <div>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isLoading && <Spinner />}
+      {data?.results.map(r => <Result key={r.id} {...r} />)}
+    </div>
+  );
+}
+```
+**Load options**:
+```tsx
+await load({
+  method: 'POST',              // GET, POST, PUT, PATCH, DELETE
+  params: { query: 'test' },   // Query string (GET) or body (others)
+  body: { data: 'value' },     // For POST/PUT/PATCH/DELETE
+});
+```
+### useLoaderData()
+Get all loader data in current context:
+```tsx
+"use client";
+import { useLoaderData } from "@rangojs/router";
+function DebugPanel() {
+  const allData = useLoaderData();
+  // Record<string, any> - Map of loader ID to data
+  return <pre>{JSON.stringify(allData, null, 2)}</pre>;
+}
+```
+## Handle Hooks
+### useHandle()
+Access accumulated handle data from route segments:
+```tsx
+"use client";
+import { useHandle } from "@rangojs/router";
+import { Breadcrumbs } from "../handles/breadcrumbs";
+function BreadcrumbNav() {
+  const crumbs = useHandle(Breadcrumbs);
+  // Array of { label, href } accumulated from layouts/routes
+  return (
+    <nav>
+      {crumbs.map((c, i) => (
+        <span key={i}>
+          <a href={c.href}>{c.label}</a>
+          {i < crumbs.length - 1 && " > "}
+        </span>
+      ))}
+    </nav>
+  );
+}
+// With selector
+const lastCrumb = useHandle(Breadcrumbs, data => data.at(-1));
+```
+Handles can be passed as props from server to client components:
+```tsx
+// Server component
+path("/dashboard", (ctx) => {
+  const push = ctx.use(Breadcrumbs);
+  push({ label: "Dashboard", href: "/dashboard" });
+  return <DashboardNav handle={Breadcrumbs} />;
+})
+// Client component — typeof infers the full Handle<T> type
+"use client";
+import { useHandle } from "@rangojs/router/client";
+import type { Breadcrumbs } from "../handles";
+function DashboardNav({ handle }: { handle: typeof Breadcrumbs }) {
+  const crumbs = useHandle(handle);
+  return <nav>{crumbs.map(c => <a href={c.href}>{c.label}</a>)}</nav>;
+}
+```
+RSC serialization strips the `collect` function via `toJSON()`. On the client,
+`useHandle()` recovers it from the module-level registry (populated when
+`createHandle()` runs during module initialization).
+## Action Hooks
+### useAction()
+Track state of server action invocations:
+```tsx
+"use client";
+import { useAction } from "@rangojs/router";
+import { addToCart } from "../actions/cart";
+function AddToCartButton({ productId }: { productId: string }) {
+  const { state, error, result } = useAction(addToCart);
+  // state: 'idle' | 'loading' | 'streaming'
+  // actionId: string | null
+  // payload: unknown | null (input data)
+  // error: Error | null
+  // result: unknown | null (return value)
+  return (
+    <form action={addToCart}>
+      <input type="hidden" name="productId" value={productId} />
+      <button disabled={state === 'loading'}>
+        {state === 'loading' ? 'Adding...' : 'Add to Cart'}
+      </button>
+      {error && <p className="error">{error.message}</p>}
+    </form>
+  );
+}
+// Match by string suffix (convenient but may be ambiguous)
+const isLoading = useAction('addToCart', s => s.state === 'loading');
+```
+## State Hooks
+### useLocationState()
+Read type-safe state from history:
+```tsx
+"use client";
+import { useLocationState, createLocationState } from "@rangojs/router";
+// Define typed state
+export const ProductState = createLocationState<{
+  name: string;
+  price: number;
+}>();
+function ProductHeader() {
+  const state = useLocationState(ProductState);
+  // { name: string; price: number } | undefined
+  if (state) {
+    return <h1>{state.name} - ${state.price}</h1>;
+  }
+  return <h1>Loading...</h1>;
+}
+```
+Pass state through Link:
+```tsx
+import { Link } from "@rangojs/router/client";
+import { ProductState } from "./state";
+<Link
+  to="/product/123"
+  state={[ProductState({ name: "Widget", price: 99 })]}
+>
+  View Product
+</Link>
+```
+## Cache Hooks
+### useClientCache()
+Manually control client-side navigation cache:
+```tsx
+"use client";
+import { useClientCache } from "@rangojs/router";
+function SaveButton() {
+  const { clear } = useClientCache();
+  const handleSave = async () => {
+    await fetch('/api/data', {
+      method: 'POST',
+      body: JSON.stringify(data)
+    });
+    // Invalidate cache after mutation
+    clear();
+  };
+  return <button onClick={handleSave}>Save</button>;
+}
+```
+**Use cases**: REST API mutations, WebSocket updates, non-RSC data changes.
+## Outlet Components
+### Outlet / ParallelOutlet
+Render child content in layouts:
+```tsx
+import { Outlet, ParallelOutlet } from "@rangojs/router";
+function DashboardLayout({ children }: { children?: React.ReactNode }) {
+  return (
+    <div className="dashboard">
+      <aside>
+        <ParallelOutlet name="@sidebar" />
+      </aside>
+      <main>
+        {children ?? <Outlet />}
+      </main>
+      <ParallelOutlet name="@notifications" />
+    </div>
+  );
+}
+```
+### useOutlet()
+Access outlet content programmatically:
+```tsx
+"use client";
+import { useOutlet } from "@rangojs/router";
+function ConditionalLayout() {
+  const outlet = useOutlet();
+  // ReactNode | null
+  return outlet ? (
+    <div className="with-content">{outlet}</div>
+  ) : (
+    <div className="empty">No content</div>
+  );
+}
+```
+## URL Hooks
+### useHref()
+Mount-aware href for client components inside `include()` scopes:
+```tsx
+"use client";
+import { useHref, href, Link } from "@rangojs/router/client";
+// Inside include("/shop", shopPatterns)
+function ShopNav() {
+  const href = useHref();
+  return (
+    <>
+      {/* Local paths - auto-prefixed with /shop */}
+      <Link to={href("/cart")}>Cart</Link>
+      <Link to={href("/product/widget")}>Widget</Link>
+    </>
+  );
+}
+```
+Use `useHref()` for local navigation. Use the bare `href()` function for absolute paths.
+### useMount()
+Returns the current `include()` mount path:
+```tsx
+"use client";
+import { useMount } from "@rangojs/router/client";
+function MountInfo() {
+  const mount = useMount(); // "/shop" inside include("/shop", ...)
+  return <span>Mounted at: {mount}</span>;
+}
+```
+See `/links` for full URL generation guide including server-side `ctx.reverse`.
+## Hook Summary
+| Hook | Purpose | Returns |
+|------|---------|---------|
+| `useHref()` | Mount-aware href | `(path) => string` |
+| `useMount()` | Current include() mount path | `string` |
+| `useNavigation()` | Navigation state & control | state, navigate, refresh |
+| `useSegments()` | URL path & segment IDs | path, segmentIds, location |
+| `useLinkStatus()` | Link pending state | { pending } |
+| `useLoader()` | Loader data (strict) | data, isLoading, error |
+| `useFetchLoader()` | Loader with on-demand fetch | data, load, isLoading |
+| `useLoaderData()` | All loader data | Record<string, any> |
+| `useHandle()` | Accumulated handle data | T (handle type) |
+| `useAction()` | Server action state | state, error, result |
+| `useLocationState()` | History state | T \| undefined |
+| `useClientCache()` | Cache control | { clear } |