@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

package/skills/breadcrumbs/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: breadcrumbs
+description: Built-in Breadcrumbs handle for accumulating breadcrumb navigation across route segments. Use when building a breadcrumb trail for nested routes, or asking how to show the current navigation path in a layout.
+argument-hint: "[setup]"
+---
+
+# Breadcrumbs
+
+Built-in handle for accumulating breadcrumb items across route segments.
+Handlers and loader bodies push items via `ctx.use(Breadcrumbs)`, and they
+are collected in parent-to-child order with automatic deduplication by
+`href`.
+
+## BreadcrumbItem Type
+
+```typescript
+interface BreadcrumbItem {
+  label: string; // Display text
+  href: string; // URL the breadcrumb links to
+  content?: ReactNode | Promise<ReactNode>; // Optional extra content (sync or async)
+}
+```
+
+## Pushing Breadcrumbs (Server)
+
+Import `Breadcrumbs` from `@rangojs/router` in RSC/server context:
+
+```typescript
+import { urls, Breadcrumbs } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
+
+export const urlpatterns = urls(({ path, layout }) => [
+  // Root layout pushes "Home"
+  layout((ctx) => {
+    const breadcrumb = ctx.use(Breadcrumbs);
+    breadcrumb({ label: "Home", href: "/" });
+    return <RootLayout />;
+  }, () => [
+    path("/", HomePage, { name: "home" }),
+
+    // Nested layout pushes "Blog"
+    layout((ctx) => {
+      const breadcrumb = ctx.use(Breadcrumbs);
+      breadcrumb({ label: "Blog", href: "/blog" });
+      return <BlogLayout />;
+    }, () => [
+      path("/blog", BlogIndex, { name: "blog.index" }),
+
+      // Route handler pushes post title
+      path("/blog/:slug", (ctx) => {
+        const breadcrumb = ctx.use(Breadcrumbs);
+        breadcrumb({ label: ctx.params.slug, href: `/blog/${ctx.params.slug}` });
+        return <BlogPost slug={ctx.params.slug} />;
+      }, { name: "blog.post" }),
+    ]),
+  ]),
+]);
+```
+
+On `/blog/my-post`, breadcrumbs accumulate: `Home > Blog > my-post`.
+
+## Pushing from Loaders
+
+A data-derived crumb belongs where the data lives — the loader body pushes
+with the same API (handler parity), so routes without handlers (`useLoader`
+consumption, `clientUrls()` groups) still build trails:
+
+```typescript
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+  const product = await getProduct(ctx.params.slug);
+
+  const pushCrumb = ctx.use(Breadcrumbs);
+  pushCrumb({ label: "Shop", href: "/shop" });
+  pushCrumb({ label: product.name, href: `/shop/product/${product.slug}` });
+
+  return product;
+});
+```
+
+Two pushes from one segment accumulate in push order (`Shop › product`).
+Delivery follows the loader race model: a push that beats the handler barrier
+is in the SSR'd document; a push after a slow fetch streams and applies
+client-side (`useHandle` re-renders when it lands). To guarantee document
+delivery, register the loader as `loader(Def, { ssr: false })` —
+see `/loader` → "Writing Handles from Loaders".
+
+## Async Content
+
+The `content` field supports `Promise<ReactNode>` for streaming:
+
+```typescript
+path("/product/:id", async (ctx) => {
+  const breadcrumb = ctx.use(Breadcrumbs);
+  const productPromise = fetchProduct(ctx.params.id);
+
+  breadcrumb({
+    label: "Product",
+    href: `/product/${ctx.params.id}`,
+    content: productPromise.then((p) => <span>({p.category})</span>),
+  });
+
+  const product = await productPromise;
+  return <ProductPage product={product} />;
+}, { name: "product" })
+```
+
+Async content is a `Promise<ReactNode>`. Resolve it in your component
+with React's `use()` hook wrapped in `<Suspense>`.
+
+### Deferred content (decide now, resolve from a deep component)
+
+When the handler should DECIDE to push a crumb early but the value is produced
+far away — by a deep async component, not the handler — call `.defer()` on the
+push function. (If the value comes from a LOADER, skip `.defer()` entirely and
+push from the loader body — see "Pushing from Loaders" above.)
+`ctx.use(Handle)` returns the push function; `.defer(options)` reserves the crumb's
+slot synchronously and returns a **resolver that is push-equal** — you call it
+later, anywhere in the render, with the same argument you'd have passed to the
+push (a value, a `Promise`, or a thunk). The only added behavior is a timeout, so a
+forgotten resolve can't hang the render (and the HTTP response): resolve-by-default
+awaits the reserved slot before any consumer reads it, and the timeout guarantees it
+settles to `else` instead of blocking forever.
+
+Reserve the slot in the handler, then resolve it from a nested async component
+that closes over the resolver — no extra wiring (the resolver is a plain closure,
+not outlet context):
+
+```tsx
+import { Breadcrumbs } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
+import { Suspense } from "react";
+
+function DocsLayout(ctx) {
+  const breadcrumb = ctx.use(Breadcrumbs);
+  // Decide now (the slot is reserved before the stream seals); resolve later.
+  const resolveCrumb = breadcrumb.defer({ timeoutMs: 5000, else: null });
+
+  // Deep, async, far from the handler — closes over the resolver, never touches ctx.
+  // Same call shape as breadcrumb({ ... }), just deferred:
+  async function LiveCrumb() {
+    const n = await countOpenIssues();
+    resolveCrumb({ label: "Docs", href: "/docs", content: <span>{n}</span> });
+    return null;
+  }
+
+  return (
+    <>
+      <Suspense>
+        <LiveCrumb />
+      </Suspense>
+      <Outlet />
+    </>
+  );
+}
+```
+
+If the resolver is never called, the slot auto-resolves to `else` after
+`timeoutMs` (default 10s) and warns in dev — graceful degradation instead of a
+hung request. `timeoutMs: 0` or `Infinity` disable the timeout intentionally; any
+other non-finite or negative value falls back to the default rather than silently
+disabling the safety net.
+
+**Consumer note (resolve-by-default):** a deferred crumb is RESOLVED before any
+consumer sees it — `useHandle(Breadcrumbs)` returns the resolved item, never a
+`Promise`, so you read it like any sync crumb (no `use()`, no thenable narrowing).
+On a full/SSR load the value is resolved server-side; on a soft navigation the
+breadcrumbs HOLD the previous resolved value until the deferred value lands, then
+swap in — no blank, no pending entry. If the slot times out to `else: null`/
+undefined, the entry is simply dropped. Use `.defer()` only when even
+`label`/`href` are unknown at handler time AND the producer is a component,
+not a loader — a loader-produced crumb pushes directly from the loader body
+(add `{ ssr: false }` if it must be in the SSR'd document), and if
+you know `label`/`href` and only the `content` is async, push a concrete item
+with a `Promise` `content` field instead (the `content` field is a nested
+promise you resolve with `use()` in your component; no `.defer()` needed).
+
+## Consuming Breadcrumbs (Client)
+
+Use `useHandle(Breadcrumbs)` in a client component to read the accumulated items:
+
+```tsx
+"use client";
+import { useHandle, Breadcrumbs, Link } from "@rangojs/router/client";
+
+function BreadcrumbNav() {
+  const breadcrumbs = useHandle(Breadcrumbs);
+
+  if (!breadcrumbs.length) return null;
+
+  return (
+    <nav aria-label="Breadcrumb">
+      <ol>
+        {breadcrumbs.map((crumb, i) => (
+          <li key={crumb.href}>
+            {i === breadcrumbs.length - 1 ? (
+              <span aria-current="page">{crumb.label}</span>
+            ) : (
+              <Link to={crumb.href}>{crumb.label}</Link>
+            )}
+          </li>
+        ))}
+      </ol>
+    </nav>
+  );
+}
+```
+
+### With Selector
+
+Re-render only when the selected value changes:
+
+```tsx
+// Only the last breadcrumb
+const current = useHandle(Breadcrumbs, (data) => data.at(-1));
+
+// Breadcrumb count
+const count = useHandle(Breadcrumbs, (data) => data.length);
+```
+
+## Deduplication
+
+The built-in collect function deduplicates by `href`. If multiple segments
+push the same `href`, the last one wins. This prevents duplicates when
+navigating between sibling routes that share a common breadcrumb.
+
+## Passing as Props
+
+Breadcrumbs handle can be passed from server to client components:
+
+```tsx
+// Server component
+path("/dashboard", (ctx) => {
+  const breadcrumb = ctx.use(Breadcrumbs);
+  breadcrumb({ label: "Dashboard", href: "/dashboard" });
+  return <DashboardNav handle={Breadcrumbs} />;
+});
+```
+
+```tsx
+// Client component
+"use client";
+import { useHandle, Breadcrumbs } from "@rangojs/router/client";
+
+function DashboardNav({ handle }: { handle: typeof Breadcrumbs }) {
+  const crumbs = useHandle(handle);
+  return (
+    <nav>
+      {crumbs.map((c) => (
+        <a href={c.href}>{c.label}</a>
+      ))}
+    </nav>
+  );
+}
+```
+
+## Complete Example
+
+```typescript
+// urls.tsx
+import { urls, Breadcrumbs, Meta } from "@rangojs/router";
+import { Outlet, MetaTags } from "@rangojs/router/client";
+import { BreadcrumbNav } from "./components/BreadcrumbNav";
+
+function RootLayout() {
+  return (
+    <html lang="en">
+      <head><MetaTags /></head>
+      <body>
+        <BreadcrumbNav />
+        <main><Outlet /></main>
+      </body>
+    </html>
+  );
+}
+
+export const urlpatterns = urls(({ path, layout }) => [
+  layout((ctx) => {
+    ctx.use(Breadcrumbs)({ label: "Home", href: "/" });
+    ctx.use(Meta)({ title: "My App" });
+    return <RootLayout />;
+  }, () => [
+    path("/", () => <h1>Welcome</h1>, { name: "home" }),
+
+    layout((ctx) => {
+      ctx.use(Breadcrumbs)({ label: "Shop", href: "/shop" });
+      return <Outlet />;
+    }, () => [
+      path("/shop", () => <h1>Shop</h1>, { name: "shop" }),
+      path("/shop/:slug", (ctx) => {
+        ctx.use(Breadcrumbs)({
+          label: ctx.params.slug,
+          href: `/shop/${ctx.params.slug}`,
+        });
+        return <h1>Product: {ctx.params.slug}</h1>;
+      }, { name: "shop.product" }),
+    ]),
+  ]),
+]);
+```
+
+Navigating to `/shop/widget` produces: `Home / Shop / widget`
+
+## Custom Handles
+
+Create your own handle with `createHandle()`:
+
+```typescript
+import { createHandle } from "@rangojs/router";
+
+// Custom collect: last value wins.
+export const PageTitle = createHandle<string, string>(
+  (segments) => segments.flat().at(-1) ?? "Default Title",
+);
+
+// No collect: the DEFAULT is the identity (lossless) — `collect` receives the
+// per-segment data (TData[][], one array per segment that pushed, in segment
+// order) and passes it through as-is. `useHandle(Warnings)` is `string[][]`, so a
+// consumer can tell which/how-many segments contributed.
+export const Warnings = createHandle<string>();
+
+// Want a single flat list instead? Opt in:
+export const FlatWarnings = createHandle<string, string[]>((segments) =>
+  segments.flat(),
+);
+```
+
+A handle whose module is never imported (so `createHandle()` never ran to register
+its collect) falls back to this same identity default and **warns in dev** — a
+handle with a custom collect that failed to register would otherwise return the
+wrong shape silently, and the runtime can't tell it from one that wanted the default.
+
+The Vite `exposeInternalIds` plugin auto-injects a stable `$$id` based on
+file path and export name. No manual naming required for project-local code.
+
+### Handles in 3rd-party packages
+
+The `exposeInternalIds` plugin skips `node_modules/`, so handles defined in
+published packages won't get auto-injected IDs. Pass a manual tag as the
+second argument to `createHandle()`:
+
+```typescript
+import { createHandle } from "@rangojs/router";
+
+// With a collect function (reducer): collect is first arg, tag is second
+export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+  collectBreadcrumbs,
+  "__my_package_breadcrumbs__",
+);
+
+// Without a collect function: pass undefined, then the tag
+export const Warnings = createHandle<string>(
+  undefined,
+  "__my_package_warnings__",
+);
+```
+
+The tag must be globally unique and stable across builds. Without it,
+`createHandle` throws in development mode.

package/skills/bundle-analysis/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: bundle-analysis
+description: Audit a Rango app's production bundle for server-side code leaking into the client, dev/prod React duplication, oversized chunks, and inefficient client-reference grouping. Use when investigating bundle size growth, before a production deploy, or when the client/SSR/RSC output suddenly balloons.
+argument-hint: "<app-dir>"
+---
+
+# Bundle Analysis
+
+Use this when you want **proof** that your Rango app is shipping the bundles you expect: small client, no server leaks, no doubled React, reasonable RSC worker size.
+
+## What this checks
+
+Your app builds in three Vite environments — `client`, `ssr`, and `rsc` — and each ships its own bundle. The most common bundle bugs in a Rango app are:
+
+1. **Server code leaking into the client.** A file that imports `node:fs`, calls a database, or contains action logic ends up in the client bundle because a client component pulled it in transitively. Symptom: your client bundle is much larger than expected, sometimes with imports that fail at runtime.
+2. **Both dev and prod React in the SSR/RSC bundle.** When `process.env.NODE_ENV` isn't folded at build time, React's CJS files ship both `.development.js` _and_ `.production.js` variants — doubling React's footprint. The Cloudflare vite plugin folds NODE_ENV automatically; vanilla `vite build` does it for client but not always for SSR/RSC.
+3. **An oversized routes-manifest in your RSC worker.** The `virtual:rsc-router/routes-manifest/<routerId>` chunk holds your route trie and precomputed entries — large only in proportion to your route count. If it's surprisingly big, you may have unintentionally generated routes (e.g., parametrized fixtures) that bloated the trie.
+4. **Inefficient client-reference grouping.** Each `"use client"` boundary becomes a chunk. Too many small client components = many tiny chunks; one giant client component = one giant chunk that defeats code-splitting.
+
+Tree-shaking does _not_ catch (1) generated data inlined as string literals or (2) data-dependent conditionals like React's. You need a visualizer.
+
+## Step 1: Install the visualizer
+
+In your app's directory:
+
+```bash
+pnpm add -D rollup-plugin-visualizer
+# or: npm install --save-dev rollup-plugin-visualizer
+# or: yarn add -D rollup-plugin-visualizer
+```
+
+## Step 2: Wire it into your `vite.config.ts`
+
+Add a small helper that registers one visualizer instance **per Vite environment** (not just one global). The plugin caches its options after the first call, so a single instance can't handle multi-environment builds — you'll get a report for one environment and silence for the others.
+
+```ts
+// vite.config.ts
+import { defineConfig, type PluginOption, type Plugin } from "vite";
+import { visualizer } from "rollup-plugin-visualizer";
+import { join } from "node:path";
+// ... your other imports ...
+
+function analyze(): PluginOption[] {
+  if (!process.env.RANGO_ANALYZE) return [];
+  return (["client", "ssr", "rsc"] as const).map((envName) => {
+    const inner = visualizer({
+      filename: join("bundle-stats", `${envName}.html`),
+      template: "treemap",
+      gzipSize: true,
+      brotliSize: true,
+    }) as Plugin;
+    return {
+      ...inner,
+      name: `analyze-${envName}`,
+      applyToEnvironment(env) {
+        return env.name === envName;
+      },
+    } as Plugin;
+  });
+}
+
+export default defineConfig(({ command }) => ({
+  plugins: [
+    // your existing plugins...
+    ...analyze(),
+  ],
+  // For non-Cloudflare apps, fold NODE_ENV explicitly so React's CJS files
+  // emit only the .production.js variants in SSR/RSC. Skip if your build
+  // setup already does this (the Cloudflare vite plugin does).
+  define:
+    command === "build"
+      ? { "process.env.NODE_ENV": JSON.stringify("production") }
+      : undefined,
+}));
+```
+
+Add `bundle-stats/` to your `.gitignore`.
+
+## Step 3: Build with the analyzer enabled
+
+```bash
+RANGO_ANALYZE=1 pnpm exec vite build
+```
+
+You'll get three HTML reports in `bundle-stats/`:
+
+- `bundle-stats/client.html` — what runs in the browser
+- `bundle-stats/ssr.html` — what runs during HTML stream
+- `bundle-stats/rsc.html` — what runs in your RSC server (Worker / Node)
+
+Open them with a quick local server (file:// has CORS issues with the embedded scripts):
+
+```bash
+pnpm dlx serve -l 5050 .
+# then visit http://localhost:5050/bundle-stats/client.html
+```
+
+## Step 4: Triage the reports
+
+### Open `client.html` first
+
+The treemap shows nested boxes; box area = uncompressed size. Hover for gzip/brotli numbers.
+
+**Look for:**
+
+- **Your server code.** Any of your own files that contain database queries, secret keys, server actions implementation (not the action _reference_), or `node:` imports. If they appear in the client treemap with non-zero bytes, they leaked. Common causes:
+  - A shared module that mixes client and server code without a `"use client"` or `"use server"` directive.
+  - A barrel file (`index.ts`) that re-exports both client and server symbols. Tree-shaking should help, but `JSON.parse('{...}')` data and side-effecting top-level statements survive.
+  - Client component imports a server-only utility through an indirect path (e.g., shared types file that pulls server modules).
+- **Multiple copies of the same package.** Look for two boxes with the same package name but different version paths. Usually means a transitive dep pinned a different version.
+- **The `@rangojs/router` chunk** should be roughly **50 KB gzip** (74 files). If significantly larger, you might be importing client-incompatible APIs from the wrong subpath.
+- **Per-route client-reference chunks** (named like `chunk-<hash>.js`). Each `"use client"` boundary can become its own chunk. If you have hundreds of tiny chunks, you may have over-split (every leaf component as a client component); if you have one massive 200 KB chunk, you've under-split (a wide client tree behind one boundary).
+
+### Now check `ssr.html`
+
+**Look for:**
+
+- **`react-dom-server.edge.development-*.js`** (or any `*.development*.js` chunk). This is the dev/prod React doubling. Fix: add `define: { "process.env.NODE_ENV": '"production"' }` to your vite config (see Step 2).
+- **Your client components** appearing in SSR. They're _expected_ here — SSR hydration needs to produce HTML for them. The same components show up in `client.html` too because the browser hydrates them. This is not a leak.
+- **Total SSR size**: a reasonable Rango SSR is ~140 KB gzip plus your app code. If it's >300 KB, almost always (1) dev/prod React duplication or (2) a giant data structure being inlined.
+
+### Now check `rsc.html`
+
+**Look for:**
+
+- **`virtual:rsc-router/routes-manifest`** should be **tiny** (< 1 KB). If it's > 100 KB, you're on an old version of `@rangojs/router` that inlined the trie eagerly — upgrade to a release that includes commit `d10a2470`.
+- **`virtual:rsc-router/routes-manifest/<hash>`** is the lazy per-router chunk. Its size is proportional to your route count. For a typical app: 5–50 KB gzip. For a stress-test app with thousands of routes: hundreds of KB. If yours is unexpectedly huge, check whether you're generating routes you don't need.
+- **`<your-router>.named-routes.gen.ts`** — generated route map. Should match your route count.
+- **Your action and loader implementations** — these run server-side. Expected to be here, not in client.
+- **Worker-incompatible code** (Node-only imports like `node:fs` that Cloudflare doesn't support). The build will usually fail before the analyzer runs, but if you're seeing runtime errors at the edge, the RSC treemap shows what made it in.
+
+## Step 5: Fix what you find
+
+| Finding                                                  | Fix                                                                                                                                                                         |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Your server code in `client.html` (non-zero bytes)       | Audit the import chain. Add `"use server"` to server-only files. Move shared data out of barrel files. Use the `@rangojs/router/server` subpath for explicitly server APIs. |
+| Your server code in `client.html` listed but 0 bytes     | Tree-shaking already eliminated it. Cosmetic. Leave it.                                                                                                                     |
+| `react-dom-server.edge.development-*.js` in SSR or RSC   | Add the `define` block from Step 2 to your vite config.                                                                                                                     |
+| Routes-manifest > 100 KB gzip in RSC eager chunk         | Update `@rangojs/router` to a release that includes the lazy-only manifest fix.                                                                                             |
+| Same package version present twice                       | Run `pnpm dedupe` (or `npm dedupe`). If the duplication persists, a transitive dep pins an incompatible version — open a PR upstream or pin the resolution.                 |
+| Client chunk > 500 KB gzip with a single dominant module | That module is your largest client component. Consider lazy-loading via dynamic `import()` or moving non-interactive parts to server components.                            |
+| Hundreds of tiny client chunks                           | You've sprinkled `"use client"` too liberally. Hoist directives to higher boundaries so React groups them.                                                                  |
+
+## When to re-run
+
+- Before every production deploy, especially after adding new dependencies.
+- After upgrading `@rangojs/router`, React, or `@vitejs/plugin-rsc`.
+- After adding routes that scale with data (e.g., one route per item from a content directory) — the manifest may have grown.
+- When CI starts reporting larger artifact sizes.
+
+## Reporting Rango regressions
+
+If a finding looks like a `@rangojs/router` regression (the framework is shipping more than it should, not your app), open an issue at the [@rangojs/router GitHub](https://github.com/ivogt/vite-rsc/issues) and include:
+
+- The output of `client.html` / `rsc.html` (screenshots or the JSON `data = {...}` block from the HTML).
+- The `@rangojs/router` version (`pnpm why @rangojs/router`).
+- Your `vite.config.ts`.
+
+The framework maintainers run a similar audit internally — the methodology in this skill mirrors what they use to validate every release.