@nifrajs/cli 4.0.2 → 5.1.0

package/docs/examples.json

@@ -47,6 +47,12 @@
     "slug": "api",
     "code": "import { server } from \"@nifrajs/core/server\"\n\nexport const app = server()\n  // /users/me is its own route; /users/42 is this one; /users/ada is a 404\n  .get(\"/users/me\", () => ({ me: true }))\n  .get(\"/users/:id{[0-9]+}\", (c) => ({ id: Number(c.params.id) }))\n  // A list of values, and a count: exactly two capital letters\n  .get(\"/img/:size{thumb|full}/:file\", (c) => ({ size: c.params.size, file: c.params.file }))\n  .get(\"/countries/:code{[A-Z]{2}}\", (c) => ({ code: c.params.code }))\n  // Inside a segment, and optional at the end of a path\n  .get(\"/files/:name.:ext{png|jpg}\", (c) => ({ name: c.params.name, ext: c.params.ext }))\n  .get(\"/posts/:page{[0-9]+}?\", (c) => ({ page: c.params.page ?? \"1\" }))"
   },
+  {
+    "name": "TYPED_ERRORS",
+    "topic": "Nifra - API & typed client",
+    "slug": "api",
+    "code": "import { client } from \"@nifrajs/client\"\nimport { server, status } from \"@nifrajs/core/server\"\nimport { t } from \"@nifrajs/schema\"\n\nconst conflict = t.object({ code: t.literal(\"conflict\"), retryAfter: t.number() })\nconst locked = new Set([\"7\"])\n\nexport const app = server().post(\"/orders/:id/pay\", { errors: { 409: conflict } }, (c) => {\n  if (locked.has(c.params.id))\n    // The body is the typed contract; the header serves proxies and plain HTTP clients.\n    return status(409, { code: \"conflict\", retryAfter: 5 }, { headers: { \"retry-after\": \"5\" } })\n  return { paid: true }\n})\n\nconst api = client<typeof app>(\"https://api.example.com\")\nconst res = await api.orders({ id: \"7\" }).pay.post()\nif (!res.ok && res.status === 409) {\n  const wait: number = res.data.retryAfter // narrowed to the declared 409 body\n}"
+  },
   {
     "name": "GUARD",
     "topic": "Nifra - Auth & sessions",
@@ -69,7 +75,7 @@
     "name": "COMPOSE",
     "topic": "Nifra - Backends & API (dev and prod)",
     "slug": "backends",
-    "code": "// backend/app.ts - compose domains with .merge(). Each group owns its FULL absolute paths.\nimport { server } from \"@nifrajs/core/server\"\n\nconst listings = server().get(\"/api/listings\", (c) => {\n  // c.req.url is the ORIGINAL request URL - .merge() and the /api mount never strip the prefix.\n  const path = new URL(c.req.url).pathname // GET /api/listings  ->  \"/api/listings\"\n  return { path }\n})\n\nconst agents = server().get(\"/api/agents\", (c) => ({ ok: new URL(c.req.url).pathname }))\n\n// merge() folds both groups into ONE flat path space at their defined paths; a path+method clash\n// throws a RouteConfigError right here at merge time (fail-closed), never a silent shadow at runtime.\nexport const backend = server().merge(listings).merge(agents)"
+    "code": "// backend/app.ts - compose domains with .merge(). Each group owns its FULL absolute paths.\nimport { server } from \"@nifrajs/core/server\"\n\nconst listings = server().get(\"/api/listings\", (c) => {\n  // c.req.url is the ORIGINAL request URL - .merge() and the /api mount never strip the prefix.\n  const path = new URL(c.req.url).pathname // GET /api/listings  ->  \"/api/listings\"\n  return { path }\n})\n\nconst agents = server().get(\"/api/agents\", (c) => ({ ok: new URL(c.req.url).pathname }))\n\n// merge() folds both groups into ONE flat path space at their defined paths; a path+method clash\n// throws a RouteConfigError right here at merge time (fail-closed), never a silent shadow at runtime.\n// A group holding .ws() routes or mount()s is refused the same way: add those on the parent.\nexport const backend = server().merge(listings).merge(agents)"
   },
   {
     "name": "EVENTS",
@@ -87,7 +93,7 @@
     "name": "WIRE",
     "topic": "Nifra - Backends & API (dev and prod)",
     "slug": "backends",
-    "code": "// backend/server.ts - a hand-written server: createWebApp serves pages AND auto-mounts the\n// backend at /api/*. (`nifra build` emits this wiring for you; write it only for a custom host.)\nimport { inProcessClient } from \"@nifrajs/client\"\nimport { createWebApp } from \"@nifrajs/web\"\nimport { reactAdapter } from \"@nifrajs/web-react\"\nimport { backend } from \"./app\"\nimport { clientEntry, manifest } from \"../server-manifest\"\n\nexport const app = createWebApp({\n  adapter: reactAdapter,\n  manifest,\n  clientEntry,\n  api: inProcessClient(backend), // → ctx.api in loaders/actions AND auto-mounted at /api/*\n  // apiPrefix: \"/api\",          // the default; pass \"\" to disable the HTTP mount (pages only)\n})\n\n// Bun: Bun.serve({ fetch: app.fetch }). No `if (pathname.startsWith(\"/api/\")) …` branch needed -\n// POST /api/sync, GET /api/me, etc. are dispatched to the backend BEFORE the page router sees them."
+    "code": "// backend/server.ts - a hand-written server: createWebApp serves pages AND mounts the\n// backend at /api/*. (`nifra build` emits this wiring for you; write it only for a custom host.)\nimport { inProcessClient } from \"@nifrajs/client\"\nimport { createWebApp } from \"@nifrajs/web\"\nimport { reactAdapter } from \"@nifrajs/web-react\"\nimport { backend } from \"./app\"\nimport { clientEntry, manifest } from \"../server-manifest\"\n\nexport const app = createWebApp({\n  adapter: reactAdapter,\n  manifest,\n  clientEntry,\n  api: inProcessClient(backend), // → ctx.api in loaders/actions\n  apiPrefix: \"/api\", // AND served over HTTP at /api/*; without it the backend is loader-only\n})\n\n// Bun: Bun.serve({ fetch: app.fetch }). No `if (pathname.startsWith(\"/api/\")) …` branch needed -\n// POST /api/sync, GET /api/me, etc. are dispatched to the backend BEFORE the page router sees them."
   },
   {
     "name": "SERVER",
@@ -195,7 +201,7 @@
     "name": "SEO_EXAMPLE",
     "topic": "Nifra - Framework contract",
     "slug": "contract",
-    "code": "// routes/articles/[slug].tsx - a complete SEO head: canonical + Open Graph + Twitter + JSON-LD,\n// with ABSOLUTE URLs built from `origin`. The three helpers (canonical/openGraph/jsonLd) are public\n// exports of @nifrajs/web; `origin` is the third MetaArgs field (after data + params).\nimport { canonical, jsonLd, openGraph, type MetaArgs } from \"@nifrajs/web\"\n\n// CAVEAT: meta() runs in BOTH SSR and client navigation, so it has NO server env - never read\n// `process.env` or the request here. The framework injects `origin` (the site's scheme+host, e.g.\n// \"https://news.example.com\") server-side from the request AND on the client from location.origin, so\n// the two match and an absolute og:url/canonical/og:image never drifts between SSR and a soft-nav. For\n// anything else server-only (an API base, a CDN host), thread it through the LOADER, not meta().\nexport const meta = ({ data, params, origin }: MetaArgs) => {\n  const article = data as { title: string; summary: string; image: string; published: string }\n  const url = `${origin}/articles/${params.slug}`        // absolute, from the injected origin\n  const image = `${origin}${article.image}`              // og:image MUST be absolute for crawlers\n  return {\n    title: article.title,\n    meta: [\n      { name: \"description\", content: article.summary },\n      // og:* - openGraph emits only the props you pass (+ og:type, here \"article\").\n      ...openGraph({\n        title: article.title,\n        description: article.summary,\n        url,\n        image,\n        type: \"article\",\n      }),\n      // twitter:* - a large-image summary card sharing the same absolute image.\n      { name: \"twitter:card\", content: \"summary_large_image\" },\n      { name: \"twitter:title\", content: article.title },\n      { name: \"twitter:description\", content: article.summary },\n      { name: \"twitter:image\", content: image },\n    ],\n    link: [canonical(url)],                              // <link rel=\"canonical\"> - the authoritative URL\n    // JSON-LD structured data - escaped for safe <script> embedding by the head renderer.\n    script: [\n      jsonLd({\n        \"@context\": \"https://schema.org\",\n        \"@type\": \"NewsArticle\",\n        headline: article.title,\n        image,\n        datePublished: article.published,\n        mainEntityOfPage: url,\n      }),\n    ],\n  }\n}"
+    "code": "// routes/articles/[slug].tsx - a complete SEO head: canonical + Open Graph + Twitter + JSON-LD,\n// with ABSOLUTE URLs built from `origin`. The three helpers (canonical/openGraph/jsonLd) come from\n// @nifrajs/web/seo, which imports nothing at runtime, so the page's browser bundle takes only them;\n// `origin` is a MetaArgs field beside data, pageData and params.\nimport type { MetaArgs } from \"@nifrajs/web\"\nimport { canonical, jsonLd, openGraph } from \"@nifrajs/web/seo\"\n\n// CAVEAT: meta() runs in BOTH SSR and client navigation, so it has NO server env - never read\n// `process.env` or the request here. The framework injects `origin` (the site's scheme+host, e.g.\n// \"https://news.example.com\") server-side from the request AND on the client from location.origin, so\n// the two match and an absolute og:url/canonical/og:image never drifts between SSR and a soft-nav. For\n// anything else server-only (an API base, a CDN host), thread it through the LOADER, not meta().\nexport const meta = ({ data, params, origin }: MetaArgs) => {\n  const article = data as { title: string; summary: string; image: string; published: string }\n  const url = `${origin}/articles/${params.slug}`        // absolute, from the injected origin\n  const image = `${origin}${article.image}`              // og:image MUST be absolute for crawlers\n  return {\n    title: article.title,\n    meta: [\n      { name: \"description\", content: article.summary },\n      // og:* - openGraph emits only the props you pass (+ og:type, here \"article\").\n      ...openGraph({\n        title: article.title,\n        description: article.summary,\n        url,\n        image,\n        type: \"article\",\n      }),\n      // twitter:* - a large-image summary card sharing the same absolute image.\n      { name: \"twitter:card\", content: \"summary_large_image\" },\n      { name: \"twitter:title\", content: article.title },\n      { name: \"twitter:description\", content: article.summary },\n      { name: \"twitter:image\", content: image },\n    ],\n    link: [canonical(url)],                              // <link rel=\"canonical\"> - the authoritative URL\n    // JSON-LD structured data - escaped for safe <script> embedding by the head renderer.\n    script: [\n      jsonLd({\n        \"@context\": \"https://schema.org\",\n        \"@type\": \"NewsArticle\",\n        headline: article.title,\n        image,\n        datePublished: article.published,\n        mainEntityOfPage: url,\n      }),\n    ],\n  }\n}"
   },
   {
     "name": "STATIC_EMIT",
@@ -203,11 +209,23 @@
     "slug": "contract",
     "code": "// build.ts - emit static HTML for opted-in routes. prerenderRoutes + cloudflarePagesRoutes\n// are PUBLIC (exported from @nifrajs/web/build) - no need to boot a server and curl it.\nimport { buildClient, prerenderRoutes, cloudflarePagesRoutes } from \"@nifrajs/web/build\"\nimport { discoverRoutes } from \"@nifrajs/web/fs\"\n\n// 1. Build the client bundle first (so the app references the hashed entry).\nawait buildClient({ routesDir: \"./routes\", outDir: \"./dist\", clientModule: \"@nifrajs/web-react/client\" })\n\n// 2. Drive the app's own fetch to render each opted-in route → dist/<path>/index.html + _data.json.\n//    Static routes opt in with `export const prerender = true`; dynamic routes enumerate concrete\n//    params with `export const getStaticPaths` (+ a `fallback: \"ssr\" | \"404\"`) - both in the\n//    route's .backend.ts.\nconst { app } = await import(\"./server\")\nconst { prerendered } = await prerenderRoutes({\n  app,                                       // the built createWebApp (a { fetch } is enough)\n  routes: discoverRoutes(\"./routes\").routes,\n  outDir: \"./dist\",\n})\n\n// 3. Hybrid deploy: a Cloudflare Pages _routes.json that serves the prerendered HTML + _data.json\n//    from the CDN and falls everything else through to the SSR worker.\nconst paths = prerendered.map((p) => p.path)\nawait Bun.write(\"./dist/_routes.json\", JSON.stringify(cloudflarePagesRoutes({ prerendered: paths })))"
   },
+  {
+    "name": "SERVER",
+    "topic": "Nifra - Control APIs (one schema, every client)",
+    "slug": "control-api",
+    "code": "import { timingSafeEqual } from \"node:crypto\"\nimport { server } from \"@nifrajs/core\"\nimport { streaming } from \"@nifrajs/core/sse\"\nimport { t, toOpenAPI } from \"@nifrajs/schema\"\n\nconst token = process.env.CONTROL_TOKEN\nif (token === undefined || token.length < 32) throw new Error(\"CONTROL_TOKEN must be 32+ characters\")\nconst expected = Buffer.from(`Bearer ${token}`)\nconst authorized = (request: Request): boolean => {\n  const given = Buffer.from(request.headers.get(\"authorization\") ?? \"\")\n  return given.length === expected.length && timingSafeEqual(given, expected)\n}\n\nconst Session = t.object({\n  id: t.string(),\n  status: t.union([t.literal(\"idle\"), t.literal(\"running\")]),\n})\nconst TurnEvent = t.object({\n  seq: t.integer({ minimum: 0 }),\n  type: t.string(),\n  text: t.optional(t.string()),\n})\n\nexport const app = server()\n  .use(streaming())\n  .onRequest((request) =>\n    authorized(request) ? undefined : Response.json({ error: \"unauthorized\" }, { status: 401 }),\n  )\n  .post(\n    \"/session/create\",\n    { body: t.object({ cwd: t.string({ minLength: 1, maxLength: 4096 }) }), response: Session },\n    () => ({ id: crypto.randomUUID(), status: \"idle\" as const }),\n  )\n  .post(\n    \"/turn/send\",\n    {\n      body: t.object({\n        sessionId: t.string(),\n        message: t.string({ minLength: 1, maxLength: 256 * 1024 }),\n      }),\n      response: t.object({ turnId: t.string() }),\n      bodyLimit: 512 * 1024,\n    },\n    () => ({ turnId: crypto.randomUUID() }),\n  )\n  .sse(\n    \"/turn/events\",\n    { query: t.object({ turnId: t.string() }), sse: TurnEvent },\n    (c, stream) => {\n      const after = Number(c.req.headers.get(\"last-event-id\") ?? -1)\n      for (let seq = after + 1; seq < 3; seq++)\n        stream.send({ seq, type: \"assistant.delta\", text: `part ${seq}` }, { id: String(seq) })\n      stream.close()\n    },\n  )\n\nexport const spec = toOpenAPI(app, { openapiVersion: \"3.2.0\", title: \"Control API\", version: \"1.0.0\" })"
+  },
+  {
+    "name": "FULL_APP",
+    "topic": "Nifra - Custom server (createWebApp)",
+    "slug": "custom-server",
+    "code": "import { fileURLToPath } from \"node:url\"\nimport { createCspPolicy, createWebApp, servePublicDir } from \"@nifrajs/web\"\nimport type { Manifest, RenderAdapter } from \"@nifrajs/web\"\n\n// From your build: the framework adapter, the route manifest, and what buildClient() returned.\ndeclare const adapter: RenderAdapter\ndeclare const manifest: Manifest\ndeclare const build: {\n  readonly entry: string\n  readonly assets: readonly string[]\n  readonly routes: Readonly<Record<string, readonly string[]>>\n  readonly css?: readonly string[]\n}\ndeclare const errors: { capture(error: unknown, tags: Record<string, string>): void }\n\n// buildClient({ outDir: \"dist/assets\" }) writes the chunks where their /assets/ URLs point.\nconst bundle = servePublicDir({\n  dir: fileURLToPath(new URL(\"./dist/\", import.meta.url)),\n  hashedFiles: new Set(build.assets),\n})\nconst publicFiles = servePublicDir({ dir: fileURLToPath(new URL(\"./public/\", import.meta.url)) })\n\nconst csp = createCspPolicy({\n  header: ({ sources }) => `default-src 'self'; script-src 'self' ${sources}; object-src 'none'`,\n})\n\nexport const app = createWebApp({\n  adapter,\n  manifest,\n  clientEntry: build.entry,\n  routePreload: build.routes,\n  styles: build.css ?? [],\n  csp,\n  server: { requestTimeoutMs: 15_000, gracefulSignals: { drainMs: 8_000 } },\n  use: (app) => {\n    app.onRequest(async (request) => (await bundle(request)) ?? (await publicFiles(request)))\n  },\n  onLoaderError: (error, { route }) => errors.capture(error, { route }),\n})\n\napp.listen(3000)"
+  },
   {
     "name": "ACTION",
     "topic": "Nifra - Loaders & actions",
     "slug": "data",
-    "code": "// routes/users/new.backend.ts - an action handles the route's POST.\nimport { t } from \"@nifrajs/schema\"\nimport type { Route } from \"./+types/new\"\n\nexport const actionOutput = t.object({ ok: t.boolean() })\n\nexport async function action({ api, request }: Route.ActionArgs) {\n  const form = await request.formData()\n  await api.users.post({ name: String(form.get(\"name\")) })\n  return { ok: true }                  // the page's loaders revalidate automatically\n}"
+    "code": "// routes/users/new.backend.ts - an action handles the route's POST.\nimport { t } from \"@nifrajs/schema\"\nimport type { Route } from \"./+types/new\"\n\nexport const actionOutput = t.object({ ok: t.boolean() })\n\nexport const action: Route.Action = async ({ api, request }) => {\n  const form = await request.formData()\n  await api.users.post({ name: String(form.get(\"name\")) })\n  return { ok: true }                  // the page's loaders revalidate automatically\n}"
   },
   {
     "name": "CONTENT",
@@ -219,7 +237,7 @@
     "name": "LOADER",
     "topic": "Nifra - Loaders & actions",
     "slug": "data",
-    "code": "// routes/users/[id].backend.ts - a loader runs on the server: in-process during SSR (no network\n// round-trip), typed against your backend contract. This file never reaches the browser.\nimport { t } from \"@nifrajs/schema\"\nimport { notFound } from \"@nifrajs/web\"\nimport type { Route } from \"./+types/[id]\"\n\n// The page receives exactly this shape. Anything else the loader returns stays on the server.\nexport const loaderOutput = t.object({ id: t.string(), name: t.string() })\n\nexport async function loader({ params, api }: Route.LoaderArgs) {\n  const res = await api.users({ id: params.id }).get()\n  if (!res.ok) throw notFound()\n  return res.data\n}"
+    "code": "// routes/users/[id].backend.ts - a loader runs on the server: in-process during SSR (no network\n// round-trip), typed against your backend contract. This file never reaches the browser.\nimport { t } from \"@nifrajs/schema\"\nimport { notFound } from \"@nifrajs/web\"\nimport type { Route } from \"./+types/[id]\"\n\n// The page receives exactly this shape. Anything else the loader returns stays on the server.\nexport const loaderOutput = t.object({ id: t.string(), name: t.string() })\n\n// Route.Loader checks what this returns against loaderOutput at compile time.\nexport const loader: Route.Loader = async ({ params, api }) => {\n  const res = await api.users({ id: params.id }).get()\n  if (!res.ok) throw notFound()\n  return res.data\n}"
   },
   {
     "name": "SHOULD_REVALIDATE",
@@ -461,6 +479,12 @@
     "slug": "plugins",
     "code": "import { server } from \"@nifrajs/core/server\"\nimport { methodOverride, trimTrailingSlash, language, timing, poweredBy, combine } from \"@nifrajs/middleware\"\n\nconst app = server()\n  .use(methodOverride())     // POST + X-HTTP-Method-Override → PUT/PATCH/DELETE (a real pre-routing request rewrite)\n  .use(trimTrailingSlash())  // canonicalize URLs: 308 redirect (or rewrite), same-origin only, conservative methods\n  .use(language({ supported: [\"en\", \"fr\"], defaultLanguage: \"en\" }))  // Accept-Language → c.language + Content-Language\n  .use(timing())             // Server-Timing header + typed c.timing marks/measures\n// poweredBy() is opt-in (Nifra emits no X-Powered-By by default). combine(a, b, c) bundles several into one plugin."
   },
+  {
+    "name": "TIERS",
+    "topic": "Nifra - Plugins & middleware",
+    "slug": "plugins",
+    "code": "import { server } from \"@nifrajs/core/server\"\nimport { MemoryStore, rateLimitTiers } from \"@nifrajs/middleware\"\n\n// Each request is charged to ONE bucket: the longest matching prefix, else the floor.\n// A tier may sit above the floor - tiers never stack on it.\nconst app = server().use(\n  rateLimitTiers({\n    store: new MemoryStore(),\n    floor: { max: 120, windowMs: 60_000 },\n    tiers: [\n      { prefix: \"/api/public\", max: 600, windowMs: 60_000 },\n      { prefix: \"/auth/login\", max: 10, windowMs: 60_000 },\n    ],\n    skip: (req) => new URL(req.url).pathname === \"/health\", // never charged\n  }),\n)"
+  },
   {
     "name": "BUILD",
     "topic": "Nifra - Rendering: SSR, streaming, SSG & ISR",
@@ -549,7 +573,7 @@
     "name": "RESPONSE_CONTRACT",
     "topic": "Nifra - security & hardening",
     "slug": "security",
-    "code": "import { server } from \"@nifrajs/core/server\"\nimport { responseContract } from \"@nifrajs/core/response-contract\"\nimport { t } from \"@nifrajs/schema\"\n\nconst PublicUser = t.object({ id: t.string(), name: t.string() })\n\n// \"warn\" logs and changes nothing; \"enforce\" makes the contract the upper bound too.\n// Not installing the plugin is \"off\" - and keeps the lane out of your bundle entirely.\nexport const app = server().use(responseContract(\"enforce\")).get(\n  \"/me\",\n  { response: PublicUser },\n  async () => {\n    // Every column, including the ones the contract never declared.\n    const user = { id: \"u1\", name: \"Ada\", email: \"a@b.c\", passwordHash: \"...\" }\n    return user\n  },\n)\n\n// off      -> {\"id\":\"u1\",\"name\":\"Ada\",\"email\":\"a@b.c\",\"passwordHash\":\"...\"}\n// enforce  -> {\"id\":\"u1\",\"name\":\"Ada\"}"
+    "code": "import { server } from \"@nifrajs/core/server\"\nimport { responseContract } from \"@nifrajs/core/response-contract\"\nimport { t } from \"@nifrajs/schema\"\n\nconst PublicUser = t.object({ id: t.string(), name: t.string() })\n\n// \"warn\" logs and changes nothing; \"enforce\" makes the contract the upper bound too.\n// Not installing the plugin is \"off\" - and keeps the lane out of your bundle entirely.\nexport const app = server().use(responseContract(\"enforce\", { extra: \"strip\" })).get(\n  \"/me\",\n  { response: PublicUser },\n  async () => {\n    // Every column, including the ones the contract never declared.\n    const user = { id: \"u1\", name: \"Ada\", email: \"a@b.c\", passwordHash: \"...\" }\n    return user\n  },\n)\n\n// off                          -> 200 {\"id\":\"u1\",\"name\":\"Ada\",\"email\":\"a@b.c\",\"passwordHash\":\"...\"}\n// enforce                      -> 500 {\"ok\":false,\"error\":\"internal_error\"}\n//                                 (t.object is closed; the log names email and passwordHash)\n// enforce, { extra: \"strip\" }  -> 200 {\"id\":\"u1\",\"name\":\"Ada\"}"
   },
   {
     "name": "SECURITY_HEADERS",
@@ -557,6 +581,12 @@
     "slug": "security",
     "code": "import { server } from \"@nifrajs/core/server\"\nimport { securityHeaders } from \"@nifrajs/middleware\"\n\n// Always on (covering errors and 404s too): X-Content-Type-Options: nosniff,\n// X-Frame-Options: DENY, Referrer-Policy: no-referrer. The rest are opt-in - each is a\n// deliberate cross-origin decision, so nifra never turns them on behind your back:\nconst app = server().use(securityHeaders({\n  crossOriginOpenerPolicy: \"same-origin\",      // isolate the browsing-context group\n  crossOriginResourcePolicy: \"same-origin\",    // block cross-origin embedding of your responses\n  crossOriginEmbedderPolicy: \"require-corp\",   // enable crossOriginIsolated (SharedArrayBuffer, …)\n  permissionsPolicy: \"camera=(), geolocation=()\",\n  contentSecurityPolicy: \"default-src 'self'\",\n  hsts: { maxAge: 63072000, includeSubDomains: true, preload: true }, // opt in once HTTPS-only\n}))"
   },
+  {
+    "name": "DEFINE",
+    "topic": "Nifra - Server components",
+    "slug": "server-components",
+    "code": "// Product.component.server.ts - native Vue/Svelte/Solid view.\nimport { t } from \"@nifrajs/schema\"\nimport { defineServerComponent, type ServerComponentContext } from \"@nifrajs/web/server-components\"\nimport { nativeServerView } from \"@nifrajs/web/server-components/islands\"\n\n// Replace these declarations with your native view and scoped read service.\ndeclare const ProductView: unknown\ndeclare function readProduct(ctx: ServerComponentContext, id: string): Promise<{ title: string; internal: string }>\n\nexport const Product = defineServerComponent({\n  input: t.object({ id: t.string({ minLength: 1 }) }),\n  props: t.object({ title: t.string() }),\n  authorize(ctx, input) {\n    if (ctx.params.id !== input.id) throw new Response(null, { status: 403 })\n  },\n  load: (ctx, input) => readProduct(ctx, input.id),\n  view: () => nativeServerView(ProductView),\n})"
+  },
   {
     "name": "DECLARE",
     "topic": "Nifra - Server functions",
@@ -581,11 +611,17 @@
     "slug": "streaming",
     "code": "import { server } from \"@nifrajs/core/server\"\nimport { sse } from \"@nifrajs/core/sse\"\n\nconst app = server()\n// Your pub-sub of choice - subscribe returns an unsubscribe function.\ndeclare const notifications: { subscribe(on: (n: { id: string }) => void): () => void }\n\n// A live feed - push events until the client disconnects.\napp.get(\"/notifications\", (c) =>\n  sse(c, (stream) => {\n    const off = notifications.subscribe((n) =>\n      stream.send({ event: \"notification\", id: n.id, data: JSON.stringify(n) }),\n    )\n    // Keep the connection open until the client leaves, then tear down.\n    return new Promise<void>((resolve) =>\n      stream.signal.addEventListener(\"abort\", () => { off(); resolve() }, { once: true }),\n    )\n  }, { keepAlive: 15_000 }),\n)"
   },
+  {
+    "name": "TYPED_SSE",
+    "topic": "Nifra - Streaming",
+    "slug": "streaming",
+    "code": "import { client } from \"@nifrajs/client\"\nimport { server } from \"@nifrajs/core/server\"\nimport { streaming } from \"@nifrajs/core/sse\"\nimport { t } from \"@nifrajs/schema\"\n\ndeclare function generate(prompt: string): AsyncIterable<string>\n\nexport const app = server()\n  .use(streaming())\n  // A GET stream: the event payload is contracted by `sse`.\n  .sse(\"/feed\", { sse: t.object({ id: t.integer(), title: t.string() }) }, (_c, stream) => {\n    stream.send({ id: 1, title: \"hello\" })\n    stream.close()\n  })\n  // A body makes it a POST stream, validated like any POST: a chat that posts its prompt.\n  .sse(\n    \"/chat\",\n    { body: t.object({ prompt: t.string() }), sse: t.object({ token: t.string() }) },\n    async (c, stream) => {\n      for await (const token of generate(c.body.prompt)) stream.send({ token })\n      stream.close()\n    },\n  )\n\nconst api = client<typeof app>(\"https://example.com\")\nconst feed = api.feed.subscribe((post) => console.log(post.title))\napi.chat.subscribe((event) => console.log(event.token), { body: { prompt: \"Hi\" } })\nfeed.close()"
+  },
   {
     "name": "BACKEND_HALF",
     "topic": "Nifra - Project structure",
     "slug": "structure",
-    "code": "// routes/users/[id].backend.ts - the page's server half. It never reaches the browser.\nimport { t } from \"@nifrajs/schema\"\nimport { notFound } from \"@nifrajs/web\"\nimport type { Route } from \"./+types/[id]\"\n\n// What the page receives - and the ONLY fields that leave the server. A field the loader returns\n// but the schema does not declare is dropped before rendering.\nexport const loaderOutput = t.object({ name: t.string(), avatarUrl: t.string() })\n\nexport async function loader({ params, api }: Route.LoaderArgs) {\n  const res = await api.users({ id: params.id }).get()\n  if (!res.ok) throw notFound()\n  return res.data\n}"
+    "code": "// routes/users/[id].backend.ts - the page's server half. It never reaches the browser.\nimport { t } from \"@nifrajs/schema\"\nimport { notFound } from \"@nifrajs/web\"\nimport type { Route } from \"./+types/[id]\"\n\n// What the page receives - and the ONLY fields that leave the server. A field the loader returns\n// but the schema does not declare is dropped before rendering; in development the console names\n// each dropped field, so a missing declaration never shows up as a silently blank page.\nexport const loaderOutput = t.object({ name: t.string(), avatarUrl: t.string() })\n\nexport async function loader({ params, api }: Route.LoaderArgs) {\n  const res = await api.users({ id: params.id }).get()\n  if (!res.ok) throw notFound()\n  return res.data\n}"
   },
   {
     "name": "BASIC",
@@ -605,6 +641,12 @@
     "slug": "testing",
     "code": "import { testClient } from \"@nifrajs/client\"\nimport { app } from \"./app\"\n\n// Every JSON response is checked against the route's declared schema for its status:\n// `response` for 2xx, `errors[status]` for declared failures. A mismatch THROWS.\nconst api = testClient<typeof app>(app, { validateResponses: true })\n\nconst res = await api.me.get()   // ResponseContractViolation if the payload drifted"
   },
+  {
+    "name": "WEB_ROUTES",
+    "topic": "Nifra - Contract-derived adversarial testing",
+    "slug": "testing",
+    "code": "// test/routes.test.ts - render the real routes in-process, each page with its backend half.\nimport { expect, test } from \"bun:test\"\nimport { createWebApp } from \"@nifrajs/web\"\nimport { discoverRoutes } from \"@nifrajs/web/fs\"\nimport { reactAdapter } from \"@nifrajs/web-react\"\n\nconst app = createWebApp({\n  adapter: reactAdapter,\n  // Scans routes/ the way the build does: a page and its .backend.ts half always arrive together.\n  manifest: discoverRoutes(`${import.meta.dir}/../routes`),\n  clientEntry: \"/client.js\",\n})\n\ntest(\"the users page runs its loader\", async () => {\n  const res = await app.fetch(new Request(\"http://localhost/users/7\"))\n  expect(res.status).toBe(200)\n})"
+  },
   {
     "name": "BACKEND_ONLY_MARKER",
     "topic": "Nifra - Troubleshooting",
@@ -658,5 +700,11 @@
     "topic": "Nifra - WebSockets",
     "slug": "websockets",
     "code": "import { server } from \"@nifrajs/core/server\"\nimport { websocket } from \"@nifrajs/core/ws\" // .use(websocket()) enables app.ws()\n\nconst app = server()\n  .use(websocket())\n  .get(\"/\", () => ({ ok: true }))\n  .ws(\"/echo\", {\n    open: (ws) => ws.send(\"welcome\"),\n    message: (ws, data) => ws.send(data), // data: string | Uint8Array\n  })\n\napp.listen(3000) // Bun"
+  },
+  {
+    "name": "COMPOSED",
+    "topic": "Nifra - WebSockets",
+    "slug": "websockets",
+    "code": "// server.ts - one listener; the chat child and a non-nifra child both take upgrades.\nimport { server } from \"@nifrajs/core/server\"\nimport { attachWebSocket, TopicRegistry, websocket, type WebSocketUpgradeOutcome } from \"@nifrajs/core/ws\"\n\nconst chat = server()\n  .use(websocket())\n  .ws(\"/room\", { message: (ws, data) => ws.send(data) })\n\n// Not a nifra server: it answers HTTP through fetch and builds its own upgrade outcome.\nconst topics = new TopicRegistry()\nconst legacy = {\n  fetch: () => new Response(\"legacy\"),\n  resolveWebSocketUpgrade: (request: Request): WebSocketUpgradeOutcome =>\n    new URL(request.url).pathname === \"/feed\"\n      ? { kind: \"upgrade\", handler: { open: (ws) => ws.send(\"hello\") }, data: undefined, pubsub: topics, attach: attachWebSocket }\n      : { kind: \"pass\" },\n}\n\nserver()\n  .use(websocket()) // Bun: the parent holds the socket table every mounted upgrade runs through\n  .mount({ path: \"/chat\", app: chat, stripPrefix: true })\n  .mount({ path: \"/legacy\", app: legacy, stripPrefix: true })\n  .listen(3000)"
   }
 ]