@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/skills/server-actions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: server-actions
-description: Define and call server actions (`"use server"`) — forms, useActionState, useOptimistic, validation, error handling, redirects, revalidation
+description: Define and call server actions (`"use server"`) — forms, useActionState, useOptimistic, validation, error handling, redirects, revalidation. Use when handling a form submission on the server, calling a server function from a client component, or needing optimistic UI after a mutation.
 argument-hint: "[action]"
 ---
 
@@ -24,7 +24,8 @@ with no framework wrapper. All standard React hooks (`useActionState`,
 Use loaders and route handlers for reads. Use actions for writes. After an
 action runs, the matched route tree can partially re-render so handlers and
 loaders that opt into revalidation see the new state — see "Revalidation"
-below.
+below. For the read-side APIs (`createLoader`, `useLoader`, `useFetchLoader`),
+see `/loader`.
 
 ## Revalidation Model
 
@@ -465,7 +466,10 @@ See `/middleware` for the full cross-segment revalidation contract.
 
 `redirect()` works inside actions. Both `return redirect(...)` and
 `throw redirect(...)` are supported and behave the same way for the
-client. Throwing is clearer when the redirect is conditional.
+client. Throwing is clearer when the redirect is conditional, and it keeps
+the action's return type narrow (e.g. `Promise<void>`) — `redirect()` returns
+a `Response`, so the `return` form needs `Promise<Response>` in the signature.
+Prefer `throw redirect(...)`; never cast with `as any`.
 
 ```typescript
 "use server";
@@ -490,6 +494,27 @@ Redirects from actions render the **target** route tree's matched segments
 source page's — the target is what the user sees next. See `/hooks
 useLocationState` for reading flash state on the target page.
 
+### Same-origin by default (open-redirect protection)
+
+`redirect()` is same-origin by default on every path — JS, no-JS PE, and
+full-page. A cross-origin target (e.g. from unvalidated user input) is blocked
+and the user is sent to the app root instead, so `redirect(userInput)` can never
+become an open redirect. To intentionally redirect off-host (an OAuth provider,
+say), opt in explicitly:
+
+```typescript
+throw redirect("https://accounts.google.com/o/oauth2/v2/auth?...", {
+  external: true,
+});
+```
+
+`{ external: true }` is the audit point: passing user input with it re-opens the
+cross-origin risk and is your responsibility (the Rails `allow_other_host: true`
+model). Omit it and off-host targets stay blocked. `external` only waives the
+**same-origin** rule, not scheme safety: the target must be `http(s)` — a
+`javascript:` or `data:` URL is still neutralized, so a forged or mistaken
+`external` target can never become a scriptable navigation.
+
 ## Error Handling
 
 ### Validation errors — return them as state

package/skills/shell-manifest/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: shell-manifest
+description: Shell manifest pattern — replayed handles as cache metadata that live loaders read, e.g. a prerendered product list with batched live prices. Use when a cached/prerendered shell needs to feed IDs or metadata to a live loader for freshly-fetched data.
+argument-hint:
+---
+
+# Shell Manifest — cache metadata for live loaders
+
+Use this when a cached or prerendered shell has dynamic holes, and the live
+data layer needs to know **what the shell actually contains** — which
+products, which slots, which keys. The frozen render describes itself
+through a handle; loaders (always live) read that description and fetch
+exactly the dynamic data the shell needs, in one batch.
+
+Canonical case: a prerendered product list where prices must stay live.
+
+## The problem this solves
+
+Any cached-shell-plus-live-holes design has a coordination gap: how does the
+live layer know what the holes need?
+
+- **Per-hole fetching** (each `<Price>` component fetching for itself) is the
+  N+1 default — N visible products, N queries.
+- **A loader that re-queries the list** ("current top products") drifts from
+  a stale shell — right prices attached to wrong products.
+
+The shell manifest closes the gap with a consistency guarantee: the loader
+reads the ids the shell _actually rendered_, replayed from the same stored
+artifact, so the holes can never desync from the shell and the query is
+batched.
+
+## The mechanism (three features composed)
+
+1. **Handles record data at render time.** The handler pushes to a handle
+   (`ctx.use(Handle)`) while it renders — at build time for `Prerender`, on
+   the cache miss for `cache()`.
+2. **Replay on every hit.** Handle data is stored with the Flight payload
+   and replayed into the handle store on cache/prerender hits — handler code
+   does not re-run, but its pushes do.
+3. **Loaders read after the render barrier.** A DSL loader can
+   `await ctx.rendered()` (waits for all non-loader segments to settle —
+   fresh render or replay alike), then `ctx.use(Handle)` returns the
+   **collected** handle data.
+
+Loaders are live by default, so the read happens on every request even when
+the shell is a hit.
+
+## Canonical example: prerendered list, live prices
+
+```tsx
+// handles/rendered-products.ts
+import { createHandle } from "@rangojs/router";
+
+// TData = string (one push per product id), collected to a flat string[]
+export const RenderedProducts = createHandle<string, string[]>((segments) =>
+  segments.flat(),
+);
+```
+
+```tsx
+// routes/products.tsx — the list is baked at build time; prices are not
+import { Prerender } from "@rangojs/router";
+import { RenderedProducts } from "../handles/rendered-products";
+import { Price } from "../components/price";
+
+export const ProductList = Prerender(
+  async () => [{ category: "espresso" }, { category: "filter" }],
+  async (ctx) => {
+    const products = await db.productsByCategory(ctx.params.category);
+    const track = ctx.use(RenderedProducts);
+    for (const p of products) track(p.id);
+    return (
+      <ul>
+        {products.map((p) => (
+          <li key={p.id}>
+            {p.name} <Price id={p.id} />
+          </li>
+        ))}
+      </ul>
+    );
+  },
+);
+```
+
+```ts
+// loaders/prices.ts — one batched query for exactly the rendered products
+import { createLoader } from "@rangojs/router";
+import { RenderedProducts } from "../handles/rendered-products";
+
+export const PriceLoader = createLoader(async (ctx) => {
+  "use server";
+  await ctx.rendered();
+  const ids = ctx.use(RenderedProducts);
+  return db.pricesFor(ids); // Map<string, number> keyed by product id
+});
+```
+
+```tsx
+// urls.tsx — wire the route and register the loader
+path("/products/:category", ProductList, { name: "products" }, () => [
+  loader(PriceLoader),
+]);
+```
+
+```tsx
+// components/price.tsx — live hole in the frozen shell
+"use client";
+import { useLoader } from "@rangojs/router/client";
+import { PriceLoader } from "../loaders/prices";
+
+export function Price({ id }: { id: string }) {
+  const { data } = useLoader(PriceLoader);
+  return <span>{formatPrice(data[id])}</span>;
+}
+```
+
+Request flow on a hit: stored payload replays (handler never runs) → handle
+data lands in the store → render barrier resolves → `PriceLoader` reads the
+replayed ids → one query → prices stream into `<Price>` components.
+
+## Works with runtime cache() too
+
+`Prerender` is build-time caching; the replay mechanism is identical for the
+runtime segment cache. Wrap the route in `cache()` instead and the handler
+pushes on the miss, replays on every hit:
+
+```tsx
+cache({ ttl: 600, tags: ["products"] }, () => [
+  path("/products/:category", ProductList, { name: "products" }, () => [
+    loader(PriceLoader),
+  ]),
+]);
+```
+
+## Contract and gotchas
+
+- **The manifest is exactly as fresh as the shell.** Replayed handle data is
+  frozen with the payload. To change _which_ products render, invalidate the
+  shell (`updateTag("products")`, TTL expiry, rebuild) — never treat the
+  loader as the refresh path for the list itself. This is the point:
+  shell and holes cannot desync because they share one artifact.
+- **No request-scoped data in a manifest handle.** The handle data is baked
+  into a shared artifact — the same cross-user rule as any cached content.
+  Ids, slugs, slot names, variant keys: yes. Anything derived from
+  `cookies()`/`headers()`: no.
+- **`ctx.rendered()` is experimental and DSL-loaders-only.** It throws in
+  fetchable/standalone loader calls that run outside a route render.
+- **The reading loader serializes after the shell.** `await ctx.rendered()`
+  deliberately gives up loader/render parallelism — on a miss the loader
+  waits for segment resolution; on a hit (the common case for a cached
+  shell) replay is immediate and the wait is negligible. A
+  `debugPerformance` waterfall shows this loader after the render bar; for
+  this pattern that is the contract, not a regression.
+- **`ctx.use(Handle)` before `await ctx.rendered()` throws** in a loader,
+  with an error saying to await the barrier first.
+- **Deferred handle values are resolved before storage** (resolve-by-default),
+  so the manifest read always sees plain values, never promises.
+
+## Testing
+
+`runLoader` seeds the barrier and the collected handle value directly —
+matched by handle reference (the same seeding style as loader deps):
+
+```ts
+import { runLoader } from "@rangojs/router/testing";
+
+const prices = await runLoader(PriceLoader, {
+  rendered: true,
+  handles: [[RenderedProducts, ["widget-a", "widget-b"]]],
+  env: { DB: fakeDb },
+});
+```
+
+This tests the loader's post-barrier logic. The real
+push → store → replay → barrier wiring is covered at the e2e tier (dev +
+production), like every cache-path behavior.
+
+## Related
+
+- `/prerender` — `Prerender`/`Passthrough`, build flow, passthrough fallback
+- `/caching` — segment `cache()`, stores, tags
+- `/loader` — loader context, `ctx.rendered()`, streaming
+- `/hooks` — `useHandle` for reading handle data in client components
+- `/rango` → "Passing data down the tree" — this pattern is the frozen→live
+  counterpart of that ladder

package/skills/streams-and-websockets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: streams-and-websockets
-description: Long-lived Response handlers — Server-Sent Events (SSE) via path.stream and WebSocket upgrades via path.any on Cloudflare Workers, including middleware interaction and runtime caveats.
+description: Long-lived Response handlers — Server-Sent Events (SSE) via path.stream and WebSocket upgrades via path.any on Cloudflare Workers, including middleware interaction and runtime caveats. Use when streaming live updates to the browser, or opening a WebSocket connection from a route on Cloudflare Workers.
 argument-hint: "[sse | websocket | agents]"
 ---
 

package/skills/tailwind/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tailwind
-description: Set up Tailwind CSS v4 with the Document component and CSS imports
+description: Set up Tailwind CSS v4 with the Document component and CSS imports. Use when adding Tailwind CSS to a Rango app, or Tailwind classes aren't being applied or generated.
 argument-hint: [setup]
 ---
 
@@ -37,7 +37,11 @@ export default defineConfig({
 
 ## Document Component
 
-Import the CSS file with `?url` to get a hashed URL, then preload and link it in `<head>`:
+Import the CSS file with `?url` to get a hashed URL, then preload and link it in
+`<head>`. Give the `<link rel="stylesheet">` a `precedence` prop so React 19
+manages it as a resource — de-duped by `href`, ordered, and loaded before paint
+(no flash of unstyled content). See
+[Stylesheets and cross-app navigation](#stylesheets-and-cross-app-navigation):
 
 ```tsx
 // src/document.tsx
@@ -51,8 +55,8 @@ export function Document({ children }: { children: ReactNode }) {
   return (
     <html lang="en">
       <head>
-        <link rel="preload" href={styles} as="style" />
-        <link rel="stylesheet" href={styles} />
+        <link rel="preload" href={styles} as="style" precedence="default" />
+        <link rel="stylesheet" href={styles} precedence="default" />
         <MetaTags />
       </head>
       <body className="font-sans antialiased text-slate-900 bg-slate-50">
@@ -63,6 +67,26 @@ export function Document({ children }: { children: ReactNode }) {
 }
 ```
 
+## Stylesheets and cross-app navigation
+
+The `precedence` prop opts a `<link rel="stylesheet">` into React 19's managed
+stylesheet model — React de-duplicates it by `href`, orders it by precedence, and
+loads it before paint (avoiding a flash of unstyled content). It is the
+recommended way to render a stylesheet link, which is why the example above uses
+it. (A bare side-effect `import "./index.css"` also produces managed CSS via
+`@vitejs/plugin-rsc`, but carries an SSR-streaming caveat — prefer the `?url` +
+`<link precedence>` form for document CSS. See `/css`.)
+
+For **host-router** apps (`/host-router`), a client-side navigation that crosses
+an app boundary is a **full document load**, not a soft swap — the framework
+redirects on an app switch. So each app's document (its stylesheets, theme, meta)
+is always re-established cleanly by the target app's own load; you do not have to
+coordinate stylesheet `href`s or `precedence` across apps. (This replaced an
+earlier soft cross-app swap, under which a stylesheet shared across apps — every
+app's `@import "tailwindcss"` compiles to one hashed asset — could be dropped by
+React's by-`href` resource dedup if the apps disagreed on `precedence`. The full
+reload removes that footgun entirely.)
+
 The `?url` suffix tells Vite to return the processed CSS file's URL instead of injecting it as a side effect. This gives you a stable, hashed asset path that works in both development and production.
 
 ## Customizing the Theme