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

package/skills/cloudflare/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: cloudflare
+description: Deploy and operate @rangojs/router on Cloudflare Workers with the Cloudflare Vite plugin, typed D1/KV bindings, local migrations, secrets, streaming, preview parity, and built-worker deployment. Use when creating a Cloudflare Rango app, moving a Rango app to Workers, wiring D1 or KV, debugging dev/preview differences, or preparing a Worker deployment.
+---
+
+# Cloudflare Workers deployment
+
+Use the Cloudflare Vite plugin as the runtime bridge. It runs the real Worker
+entry in workerd during `vite dev` and `vite preview`, supplies bindings, and
+emits the deployable Worker configuration during `vite build`.
+
+## Install and configure
+
+```bash
+pnpm add @rangojs/router react react-dom
+pnpm add -D vite @vitejs/plugin-react @cloudflare/vite-plugin \
+  @cloudflare/workers-types wrangler typescript
+```
+
+Keep plugin order stable: React first, then Rango, then Cloudflare.
+
+```typescript
+// vite.config.ts
+import { cloudflare } from "@cloudflare/vite-plugin";
+import react from "@vitejs/plugin-react";
+import { rango } from "@rangojs/router/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    rango({ preset: "cloudflare", buildEnv: "auto" }),
+    cloudflare({
+      configPath: "./wrangler.json",
+      viteEnvironment: { name: "rsc", childEnvironments: ["ssr"] },
+    }),
+  ],
+});
+```
+
+`buildEnv: "auto"` exposes build-safe bindings to static/prerender collection.
+Omit it when build rendering must not access bindings.
+
+```json
+{
+  "name": "my-rango-app",
+  "compatibility_date": "2025-10-01",
+  "compatibility_flags": ["nodejs_compat", "nodejs_als"],
+  "main": "./src/worker.rsc.tsx",
+  "assets": { "directory": "./dist/client" }
+}
+```
+
+## Type bindings once
+
+```typescript
+// src/env.ts
+/// <reference types="@cloudflare/workers-types" />
+
+export interface AppBindings {
+  DB: D1Database;
+  CACHE_KV: KVNamespace;
+}
+
+declare global {
+  namespace Rango {
+    interface Env extends AppBindings {}
+  }
+}
+```
+
+Rango's runtime entries stay as TypeScript source for Vite to bundle, while its
+package `types` conditions point to emitted declarations. A Workers-only app
+does not need `@types/node` just to type-check Rango:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@cloudflare/workers-types", "vite/client"]
+  }
+}
+```
+
+## Preserve the response stream
+
+```typescript
+// src/worker.rsc.tsx
+/// <reference types="@cloudflare/workers-types" />
+import { router } from "./router.js";
+import type { AppBindings } from "./env.js";
+
+export default {
+  fetch(request, env, ctx) {
+    return router.fetch(request, { env, ctx });
+  },
+} satisfies ExportedHandler<AppBindings>;
+```
+
+Do not call `response.text()` or `response.arrayBuffer()` on the Rango response
+in a custom Worker entry. That drains RSC/SSR streaming. Rewrap
+`new Response(response.body, response)` when only headers must change.
+
+## Choose the next reference
+
+- D1/KV setup, local migrations, `.dev.vars`, and parity tests: read
+  [references/d1-and-local-dev.md](references/d1-and-local-dev.md).
+- Streaming diagnostics, preview behavior, CORS, and deploy output: read
+  [references/streaming-and-deploy.md](references/streaming-and-deploy.md).
+- Raw-body webhooks, WebCrypto, and Stripe-on-Workers notes: read
+  [references/webhooks-and-crypto.md](references/webhooks-and-crypto.md).
+
+## Cache on Workers
+
+Use the Cache API as L1 and KV as optional cross-colo L2:
+
+```typescript
+import { CFCacheStore } from "@rangojs/router/cache";
+
+export const router = createRouter<AppBindings>({
+  document: Document,
+  urls: urlpatterns,
+  cache: (env, ctx) => ({
+    store: new CFCacheStore({
+      ctx,
+      kv: env.CACHE_KV,
+      defaults: { ttl: 60, swr: 300 },
+    }),
+  }),
+});
+```
+
+PPR shells use Cache API as the per-colo L1 and KV as the durable cross-colo
+L2; a KV hit promotes the coupled shell envelope back into L1. KV is optional:
+`CFCacheStore` without `kv` runs the shell family L1-only (edge-only ppr —
+each colo captures and serves its own shell). Tag eviction then needs purge
+mode (`tagPurge`); a tagged shell without either warns once and expires by
+ttl+swr only.
+
+## Commands
+
+```jsonc
+{
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview",
+    "deploy": "wrangler deploy -c dist/rsc/wrangler.json",
+  },
+}
+```
+
+Use `vite dev` and `vite preview` for local RSC work. Reserve Wrangler for
+resource provisioning, migrations, secrets, and deployment.

package/skills/cloudflare/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Cloudflare deployment"
+  short_description: "Deploy Rango on Cloudflare Workers with D1 and KV"
+  default_prompt: "Use $cloudflare to configure and deploy a Rango app on Cloudflare Workers with typed bindings."

package/skills/cloudflare/references/d1-and-local-dev.md

@@ -0,0 +1,131 @@
+# D1, KV, and local parity
+
+## Contents
+
+- [Provision bindings](#provision-bindings)
+- [Apply D1 migrations](#apply-d1-migrations)
+- [Use bindings](#use-bindings)
+- [Load local secrets](#load-local-secrets)
+- [Test dev and production-shaped preview](#test-dev-and-production-shaped-preview)
+
+## Provision bindings
+
+Create real resource IDs before the first deploy:
+
+```bash
+pnpm exec wrangler d1 create my-app
+pnpm exec wrangler kv namespace create CACHE_KV
+```
+
+Copy the returned IDs into `wrangler.json`:
+
+```json
+{
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "my-app",
+      "database_id": "<d1-id>",
+      "migrations_dir": "migrations"
+    }
+  ],
+  "kv_namespaces": [{ "binding": "CACHE_KV", "id": "<kv-id>" }]
+}
+```
+
+Do not deploy placeholder IDs. Keep binding names identical in `wrangler.json`
+and `AppBindings`; `ctx.env.DB` is the configured binding, not a global.
+
+## Apply D1 migrations
+
+```bash
+# Generate SQL with your migration tool first, then:
+pnpm exec wrangler d1 migrations apply my-app --local
+pnpm exec wrangler d1 migrations apply my-app --remote
+```
+
+The Cloudflare Vite plugin and `wrangler d1 ... --local` use the same local
+Miniflare persistence for the project. A migration applied through the CLI is
+therefore visible to both `vite dev` and `vite preview`; treat the internal
+`.wrangler/state` layout as an implementation detail.
+
+Add a real handler probe while setting up the binding, then remove it after the
+first production-shaped test:
+
+```typescript
+path.json("/__db-check", async (ctx) => {
+  const row = await ctx.env.DB.prepare(
+    "SELECT COUNT(*) AS n FROM users",
+  ).first<{
+    n: number;
+  }>();
+  return { ok: true, users: row?.n ?? 0 };
+});
+```
+
+## Use bindings
+
+Handlers, loaders, and middleware all receive the same typed bindings:
+
+```typescript
+export const UserLoader = createLoader(async (ctx) =>
+  ctx.env.DB.prepare("SELECT * FROM users WHERE id = ?")
+    .bind(ctx.params.id)
+    .first(),
+);
+
+export const requireSession: Middleware = async (ctx, next) => {
+  const token = cookies().get("session")?.value;
+  const session = token
+    ? await ctx.env.DB.prepare("SELECT * FROM sessions WHERE token = ?")
+        .bind(token)
+        .first()
+    : null;
+  if (!session) return redirect("/login");
+  return next();
+};
+```
+
+D1 has no Postgres RLS. Moving from an RLS-backed database requires an
+authorization-aware data-access layer that checks actor/tenant membership as
+part of every query. Do not translate SQL tables while silently dropping RLS.
+
+## Load local secrets
+
+Keep `.dev.vars` out of git and commit `.dev.vars.example` with names only:
+
+```dotenv
+SESSION_SECRET=
+STRIPE_WEBHOOK_SECRET=
+```
+
+Loading differs by command:
+
+| Command        | Source                                                      |
+| -------------- | ----------------------------------------------------------- |
+| `vite dev`     | live project `.dev.vars`                                    |
+| `vite preview` | `dist/<environment>/.dev.vars` copied during the last build |
+| `wrangler dev` | project `.dev.vars`                                         |
+
+Rebuild after changing `.dev.vars` before testing preview. Use
+`wrangler secret put NAME` for production secrets; `.dev.vars` is local only.
+
+Keep behavior-forcing e2e flags separate from a developer's default local
+profile. A copied `.dev.vars.example` that enables every production gate makes
+the documented "easy local dev" mode false.
+
+## Test dev and production-shaped preview
+
+Run the same behavior suite twice:
+
+1. `vite dev` against the source/module-runner path.
+2. `vite build`, then `vite preview` against the bundled Worker in workerd.
+
+Seed external-provider state offline where possible. For example, sign a test
+webhook with a fixed local webhook secret and assert the real D1 effect instead
+of provisioning a live payment account.
+
+When Playwright manages the servers, run dev and preview sequentially if they
+share the build directory or local D1 state. Set `inspectorPort: false` in the
+Cloudflare plugin for automated runs that do not use the debugger, or assign
+explicit distinct ports.

package/skills/cloudflare/references/streaming-and-deploy.md

@@ -0,0 +1,107 @@
+# Streaming, preview, and deployment
+
+## Contents
+
+- [Keep streamed responses intact](#keep-streamed-responses-intact)
+- [Use Vite for local RSC work](#use-vite-for-local-rsc-work)
+- [Handle route-owned CORS](#handle-route-owned-cors)
+- [Deploy the built Worker](#deploy-the-built-worker)
+- [Debug a dev-preview difference](#debug-a-dev-preview-difference)
+
+## Keep streamed responses intact
+
+Anything that awaits the full Rango response body removes streaming:
+
+```typescript
+// Wrong: drains the stream.
+const response = await router.fetch(request, { env, ctx });
+const html = await response.text();
+return new Response(rewrite(html), response);
+
+// Correct: preserve the body stream while changing headers.
+const response = await router.fetch(request, { env, ctx });
+const headers = new Headers(response.headers);
+headers.set("X-App", "worker");
+return new Response(response.body, {
+  status: response.status,
+  statusText: response.statusText,
+  headers,
+});
+```
+
+Keep buffering on a legacy proxy branch if it is required there, but never run
+it on the `router.fetch()` branch.
+
+## Use Vite for local RSC work
+
+Use `vite dev` and `vite preview`. The Cloudflare Vite plugin runs the Worker
+inside Miniflare/workerd with the same binding shape as deployment.
+
+Avoid diagnosing streaming with `wrangler dev`: local gzip compression can
+buffer the response. If that tool is unavoidable, compare
+`Accept-Encoding: identity` and `Accept-Encoding: gzip` before blaming the
+router. Deployed Cloudflare compression streams.
+
+Verify first-byte behavior directly:
+
+```bash
+curl --no-buffer --raw -H 'Accept-Encoding: identity' http://localhost:5173/slow
+```
+
+## Handle route-owned CORS
+
+Vite's CORS middleware answers preflight `OPTIONS` before the Worker in both
+`vite dev` and `vite preview` by default. A preview preflight therefore does not
+prove that the deployed route's own `OPTIONS` branch works.
+
+When the Worker must own exact CORS headers, disable the outer Vite CORS layer
+in both modes:
+
+```typescript
+export default defineConfig({
+  server: { cors: false },
+  preview: { cors: false },
+  // plugins...
+});
+```
+
+Assert the full CORS set on a real non-preflight response as well as the route's
+`OPTIONS` response. Keep a deployed smoke check for the final edge behavior.
+
+## Deploy the built Worker
+
+`vite build` writes client assets to `dist/client` and a deployable Worker
+configuration under the RSC environment output, normally
+`dist/rsc/wrangler.json`. That generated config points at the bundled Worker and
+sets the client asset directory correctly.
+
+```bash
+pnpm exec vite build
+pnpm exec wrangler deploy -c dist/rsc/wrangler.json
+```
+
+Do not deploy the source `main` from the root config after building. Wrangler's
+bundler cannot reconstruct Rango's Vite virtual modules. If the RSC environment
+has a custom name, use its matching `dist/<name>/wrangler.json` path.
+
+Before deployment:
+
+- replace placeholder D1/KV IDs;
+- apply remote D1 migrations;
+- provision each production secret with `wrangler secret put`;
+- run the preview parity suite against a fresh build;
+- confirm no server-only secret appears in `dist/client`;
+- smoke-test streaming and redirects on the deployed edge.
+
+## Debug a dev-preview difference
+
+1. Build immediately before preview; stale `dist` output invalidates the test.
+2. Compare the actual `.dev.vars`/bindings visible in each mode.
+3. Send `Accept: text/html` or no `Accept` for a document request; send
+   `Accept: text/x-component` only when testing Flight.
+4. Disable automatic redirect following when inspecting a 3xx.
+5. Test the target URL first on a fresh preview process, then after the redirect.
+6. Capture both curl timing and the Worker's request log. A request absent from
+   the Worker log is stuck in the outer Vite/Cloudflare layer.
+7. Reduce the case to one route before assigning ownership to Rango, Vite, or
+   the Cloudflare plugin.

package/skills/cloudflare/references/webhooks-and-crypto.md

@@ -0,0 +1,147 @@
+# Webhooks and WebCrypto on Workers
+
+## Contents
+
+- [Read the original request body](#read-the-original-request-body)
+- [Test signed webhooks offline](#test-signed-webhooks-offline)
+- [Port Node crypto carefully](#port-node-crypto-carefully)
+- [Use Stripe 22 on workerd](#use-stripe-22-on-workerd)
+- [Keep SDKs off the cold path](#keep-sdks-off-the-cold-path)
+
+## Read the original request body
+
+Signature verification must receive the exact bytes sent by the provider:
+
+```typescript
+path.json("/api/webhook", async (ctx) => {
+  const rawBody = await ctx.request.text();
+  const signature = ctx.request.headers.get("provider-signature");
+  await verify(rawBody, signature);
+  return { ok: true };
+});
+```
+
+`path.json` describes the response representation; it does not parse or
+reserialize the incoming request. Use `path.any` only when the handler needs a
+fully manual `Response` contract or several methods/representations.
+
+## Test signed webhooks offline
+
+Use a fixed, non-production secret in the e2e environment. For Stripe, serialize
+the body once, sign `${timestamp}.${rawBody}`, format the real
+`stripe-signature` header, and send the same string:
+
+```typescript
+const rawBody = JSON.stringify(event);
+const key = await crypto.subtle.importKey(
+  "raw",
+  new TextEncoder().encode(WEBHOOK_SECRET),
+  { name: "HMAC", hash: "SHA-256" },
+  false,
+  ["sign"],
+);
+const signature = await crypto.subtle.sign(
+  "HMAC",
+  key,
+  new TextEncoder().encode(`${timestamp}.${rawBody}`),
+);
+const hex = Array.from(new Uint8Array(signature), (byte) =>
+  byte.toString(16).padStart(2, "0"),
+).join("");
+
+await request.post("/api/webhook", {
+  data: rawBody,
+  headers: {
+    "content-type": "application/json",
+    "stripe-signature": `t=${timestamp},v1=${hex}`,
+  },
+});
+```
+
+Assert the real D1 mutation through the public application route. Run the case
+under both dev and preview. Do not pass an object to the HTTP client after
+signing a string; another serialization can invalidate the signature.
+
+## Port Node crypto carefully
+
+TypeScript 5.9 defaults `Uint8Array` to `Uint8Array<ArrayBufferLike>`, while DOM
+WebCrypto accepts `ArrayBufferView<ArrayBuffer>`. Annotate byte-producing
+helpers that feed `crypto.subtle` precisely:
+
+```typescript
+function fromBase64(value: string): Uint8Array<ArrayBuffer> {
+  const bytes = new Uint8Array(atob(value).length);
+  // fill bytes...
+  return bytes;
+}
+```
+
+WebCrypto AES-GCM returns `ciphertext || authenticationTag`. When preserving a
+Node format that stored the tag separately, split the final 16 bytes on encrypt
+and append them again before decrypting.
+
+## Use Stripe 22 on workerd
+
+Stripe 22 publishes a `workerd` export whose defaults use `fetch` and
+SubtleCrypto. Webhook verification must use the asynchronous API; the sync API
+cannot run a SubtleCrypto provider synchronously:
+
+```bash
+pnpm add stripe@^22
+```
+
+```typescript
+import Stripe from "stripe";
+
+path.json("/api/webhooks/stripe", async (ctx) => {
+  const rawBody = await ctx.request.text();
+  const signature = ctx.request.headers.get("stripe-signature");
+  if (!signature) throw new Response("Missing signature", { status: 400 });
+
+  const event = await Stripe.webhooks.constructEventAsync(
+    rawBody,
+    signature,
+    ctx.env.STRIPE_WEBHOOK_SECRET,
+  );
+
+  await ctx.env.DB.prepare(
+    "INSERT OR IGNORE INTO stripe_events (id, type, payload) VALUES (?, ?, ?)",
+  )
+    .bind(event.id, event.type, rawBody)
+    .run();
+  return { received: true };
+});
+```
+
+Use a small idempotency table for the offline assertion:
+
+```sql
+CREATE TABLE stripe_events (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  received_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+Using `Stripe.createFetchHttpClient()` and
+`Stripe.createSubtleCryptoProvider()` explicitly is defensive but not required
+when the `workerd` export is selected. Static `Stripe.webhooks` also means
+signature verification does not require a fabricated API key or Stripe client
+instance. The webhook signing secret, not the API secret key, authenticates the
+payload.
+
+These defaults are specific to Stripe 22. Revalidate the export map and crypto
+provider behavior when upgrading the SDK major.
+
+## Keep SDKs off the cold path
+
+Put a large, rarely used webhook/billing group behind an async include:
+
+```typescript
+include("/", () => import("./urls/billing.js"), { name: "billing" });
+```
+
+Measure a before/after production build before claiming an SDK's incremental
+cost. A chunk that contains the SDK is not itself proof that every byte was
+introduced by that dependency.

package/skills/comparison/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: comparison
+description: Compare Rango with Next.js App Router, TanStack Start, and Waku. Use when evaluating React frameworks, explaining why Rango, writing positioning or adoption guidance, answering migration questions, or checking claims about Rango's routing, loaders, caching, rendering, prefetching, safety, testing, observability, and production behavior.
+---
+
+# Compare Rango with other React frameworks
+
+Use the canonical [framework comparison](references/framework-comparison.md) as
+the factual baseline. Read the sections relevant to the question; read the full
+reference when producing an overall evaluation or editing the comparison itself.
+
+## Comparison rules
+
+1. Compare capabilities and architecture separately from ecosystem size, hiring,
+   integrations, and organizational familiarity.
+2. Present Rango's range clearly: start with `path()` and a component, then add
+   named routes, `include()`, loaders, caching, `revalidate()`, slots, intercepts,
+   safety, and diagnostics in the same declared route graph.
+3. Do not confuse Rango's `revalidate()` with cache invalidation. Cache APIs decide
+   stored-value freshness; `revalidate()` decides client render selection.
+4. Describe loaders as live-by-default RSC data slots beneath cached or prerendered
+   UI, not as renamed Remix or TanStack route loaders.
+5. Include production correctness where relevant: Rango State, userland client-cache
+   invalidation, deployment-skew recovery, tainted request context, CSP nonce
+   propagation, default CSRF origin checks, prefetch guards, testing, and timing.
+6. State boundaries and tradeoffs. In particular, distinguish origin checking from
+   token-based CSRF protection, nonce plumbing from application-owned CSP policy,
+   and reload-based skew recovery from Vercel deployment pinning.
+7. Credit competing frameworks where they lead. Next.js leads in ecosystem and
+   hiring, TanStack in search-param ergonomics and client/data devtools, and Waku
+   in minimal surface area.
+
+## Currency and evidence
+
+- Treat Rango identifiers and behavior as source-verifiable. Check the current
+  package source or the relevant Rango skill when changing a precise claim.
+- Competitor details age quickly. Before publishing or materially revising a claim,
+  verify it against current official documentation and link that primary source.
+- Do not weaken a current, sourced claim merely because an older model remembers a
+  previous release. Check first: examples include TanStack Start's Rsbuild support,
+  Next.js `proxy.ts` and Cache Components, and Waku handler interceptors.
+- Avoid declaring a framework universally "better." State which model fits the
+  application's constraints and why.
+
+## Output shape
+
+Lead with the decision or differentiator. For a short answer, use the TL;DR and the
+relevant framework-specific paragraph from the reference. For a decision memo,
+cover the at-a-glance table, the simple-to-complex growth path, substantive runtime
+differences, and the section where competitors still lead.

package/skills/comparison/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Rango Comparison"
+  short_description: "Compare Rango with other React frameworks"
+  default_prompt: "Use $comparison to compare Rango with Next.js, TanStack Start, and Waku."