netjes 0.0.0-stage → 0.0.2

package/sidecar/server.mjs

@@ -0,0 +1,325 @@
+// @ts-check
+// The Netjes sidecar: renders pages for the .NET server over loopback HTTP. Started and supervised by NodeSidecar.cs.
+//   development: hosts the Vite dev server (HMR for the browser) and renders with fresh modules on every request.
+//   production:  renders with the prebuilt dist/server/server-entry.js.
+// Protocol: POST /render with the HTML-safe page payload JSON as body -> 200 text/html, streamed from the moment the
+// shell is ready (or once everything is, with X-Netjes-Wait-All: 1), or 500 {"error":{message,stack}} in plain text
+// (no terminal colours) if the shell fails. Every request must carry the X-Netjes-Token the parent passed in
+// NETJES_TOKEN. Renders are aborted when the caller disconnects, when the shell is not ready after
+// NETJES_RENDER_TIMEOUT_MS, or when the whole stream takes longer than NETJES_STREAM_TIMEOUT_MS. Exits when stdin
+// closes.
+// Startup: prints NETJES_READY {"port","viteOrigin"} on stdout once it listens. When the Vite dev server does not start,
+// it prints NETJES_FAILED and exits with code 1: {"reason":"vite-port-in-use","port"} when its port is taken, and
+// {"reason":"vite-failed","message","code"} for anything else, such as an error in vite.config or a package it imports
+// that is not installed (message in plain text; code is the error's when it has one, such as ERR_MODULE_NOT_FOUND, or
+// MODULE_NOT_FOUND from a CommonJS config).
+import http from 'node:http';
+import { pipeline } from 'node:stream/promises';
+import { pathToFileURL } from 'node:url';
+
+const mode = process.env.NETJES_MODE === 'development' ? 'development' : 'production';
+const root = process.env.NETJES_ROOT ?? process.cwd();
+const token = process.env.NETJES_TOKEN ?? '';
+// Without a token the guard below would accept a request that sends an empty X-Netjes-Token header.
+if (!token) throw new Error('NETJES_TOKEN is required: the sidecar is started by Netjes, which sets it');
+// Page code runs in this process; it has no business knowing the token.
+delete process.env.NETJES_TOKEN;
+const renderTimeoutMs = Number(process.env.NETJES_RENDER_TIMEOUT_MS ?? 15_000);
+const streamTimeoutMs = Number(process.env.NETJES_STREAM_TIMEOUT_MS ?? 60_000);
+const vitePort = Number(process.env.NETJES_VITE_PORT ?? 5173);
+const MAX_BODY_BYTES = 16 * 1024 * 1024;
+const CSS_FILE = /\.(css|less|sass|scss|styl|stylus|pcss|postcss|sss)$/;
+// Terminal escape sequences (ECMA-48): CSI, as ESC [ or its one-character form (colours, as in Vite's code frames, which
+// it colours in a pipe too), strings such as OSC (links), and the other escapes (a cursor save, say). An error page
+// shows them as text, and a log file keeps them as such. Not Node's stripVTControlCharacters, which after ESC 7 (that
+// cursor save) can take the next letter too. NodeSidecar.cs strips this process's output with the same pattern.
+const TERMINAL_ESCAPES = /(?:\u001b\[|\u009b)[0-?]*[ -/]*[@-~]|\u001b[\]PX^_][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b[ -/]*[0-~]/g;
+
+/** @param {string} text */
+const plainText = (text) => text.replace(TERMINAL_ESCAPES, '');
+
+/** @typedef {{ signal: AbortSignal, waitForAll?: boolean, deferred?: (id: string) => PromiseLike<unknown> }} RenderOptions */
+/** @type {(data: string, options: RenderOptions) => Promise<string>} */
+let render;
+/** @type {((data: string, options: RenderOptions) => Promise<import('node:stream').Readable>) | undefined} */
+let renderToStream;
+/** @type {import('vite').ViteDevServer | undefined} */
+let vite;
+
+/**
+ * Says why the Vite dev server did not start, for .NET to report in a line of its own (Node's report of an uncaught
+ * error would bury it under its stack trace), and exits.
+ * @param {Record<string, unknown>} failed
+ * @returns {Promise<never>}
+ */
+async function failStartup(failed) {
+  await new Promise((resolve) => process.stdout.write(`NETJES_FAILED ${JSON.stringify(failed)}\n`, resolve));
+  process.exit(1);
+}
+
+/** @param {unknown} error */
+const viteFailed = (error) =>
+  failStartup({
+    reason: 'vite-failed',
+    message: plainText(error instanceof Error ? error.message : String(error)),
+    code: error instanceof Error && 'code' in error && typeof error.code === 'string' ? error.code : undefined,
+  });
+
+if (mode === 'development') {
+  const origin = process.env.NETJES_VITE_ORIGIN ?? `http://localhost:${vitePort}`;
+  /** @type {import('vite').ViteDevServer} */
+  let dev;
+  try {
+    // Vite is the app's own dependency; it fails here when it is not installed, and on an error in vite.config.
+    const { createServer } = await import('vite');
+    dev = await createServer({
+      root,
+      appType: 'custom',
+      clearScreen: false,
+      server: { port: vitePort, strictPort: true, origin, host: process.env.NETJES_VITE_HOST || undefined },
+    });
+  } catch (error) {
+    // It exits, so dev is set from here on.
+    dev = await viteFailed(error);
+  }
+  vite = dev;
+  try {
+    await dev.listen();
+  } catch (error) {
+    // Most often another app's Vite dev server: .NET names the port and how to move it.
+    if (error instanceof Error && error.message === `Port ${vitePort} is already in use`) {
+      await failStartup({ reason: 'vite-port-in-use', port: vitePort });
+    }
+    await viteFailed(error);
+  }
+  /** The netjes plugin's development API (vite/plugin.mjs). */
+  const netjes = /** @type {{ rescanPages(): void } | undefined} */ (dev.config.plugins.find((plugin) => plugin.name === 'netjes')?.api);
+  /**
+   * Runs a render with the server entry. .NET routes a page file as soon as its own watcher sees it, but the page
+   * module map changes only when Vite's watcher reports a page file, which for this one can be much later (a file it
+   * missed is reported once something else changes in its folder) or never (a folder Vite does not watch). A render
+   * that names a file the map lacks has the plugin build the map again from the files on disk, and runs once more.
+   * @template T
+   * @param {(entry: Awaited<ReturnType<typeof dev.ssrLoadModule>>) => Promise<T>} run
+   */
+  const withServerEntry = async (run) => {
+    try {
+      return await run(await dev.ssrLoadModule('netjes/server-entry'));
+    } catch (error) {
+      if (!netjes || !(error instanceof Error) || error.name !== 'MissingModuleError') throw error;
+      netjes.rescanPages();
+      return run(await dev.ssrLoadModule('netjes/server-entry'));
+    }
+  };
+  render = async (data, options) => {
+    const styled = await withDevStyles(dev, data);
+    return withServerEntry((entry) => entry.render(styled, options));
+  };
+  renderToStream = async (data, options) => {
+    const styled = await withDevStyles(dev, data);
+    return withServerEntry((entry) => entry.renderToStream(styled, options));
+  };
+} else {
+  const entry = process.env.NETJES_SERVER_ENTRY;
+  if (!entry) throw new Error('NETJES_SERVER_ENTRY is not set');
+  ({ render, renderToStream } = await import(pathToFileURL(entry).href));
+}
+
+/**
+ * Inlines the CSS imported by the page and its segment files, so the server-rendered page is styled before the client
+ * script runs. Vite's client adopts these <style data-vite-dev-id> tags and keeps them updated through HMR.
+ * @param {import('vite').ViteDevServer} server
+ * @param {string} data
+ */
+async function withDevStyles(server, data) {
+  const payload = JSON.parse(data);
+  /** @type {Array<Record<string, unknown>>} */
+  const segments = payload.segments ?? [];
+  const files = [...segments.flatMap((s) => [s.layout, s.template, s.loading, s.error]), payload.page].filter(
+    (file) => typeof file === 'string',
+  );
+  const environment = server.environments.ssr;
+  /** @type {Map<string, string>} */
+  const styles = new Map();
+  /** @type {Set<string>} */
+  const seen = new Set();
+
+  /** @param {import('vite').EnvironmentModuleNode | undefined} node */
+  async function collect(node) {
+    if (!node?.id || seen.has(node.id)) return;
+    seen.add(node.id);
+    if (node.file && CSS_FILE.test(node.file) && !node.id.includes('?')) {
+      const css = await server.ssrLoadModule(`${node.url}?inline`);
+      styles.set(node.file, String(css.default));
+      return;
+    }
+    for (const imported of node.importedModules) await collect(imported);
+  }
+
+  for (const file of files) {
+    await server.ssrLoadModule(`/${file}`);
+    await collect(await environment.moduleGraph.getModuleByUrl(`/${file}`));
+  }
+  if (styles.size === 0) return data;
+  payload.document.devStyles = [...styles].map(([id, css]) => ({ id, css }));
+  return JSON.stringify(payload).replace(/[<>&\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+
+/**
+ * Page.Defer values per render, as .NET posts them to /resolve. Values may arrive before the render asks for them;
+ * entries nobody claims are dropped after the stream timeout.
+ * @typedef {{ promise: Promise<unknown>, resolve: (value: unknown) => void, reject: (error: Error) => void }} Pending
+ * @type {Map<string, { values: Map<string, Pending>, timer: NodeJS.Timeout }>}
+ */
+const renders = new Map();
+
+/** @param {string} renderId */
+function renderEntry(renderId) {
+  let entry = renders.get(renderId);
+  if (!entry) {
+    const timer = setTimeout(() => renders.delete(renderId), streamTimeoutMs + 5_000);
+    timer.unref();
+    entry = { values: new Map(), timer };
+    renders.set(renderId, entry);
+  }
+  return entry;
+}
+
+/** @param {string} renderId @param {string} id */
+function pendingValue(renderId, id) {
+  const { values } = renderEntry(renderId);
+  let pending = values.get(id);
+  if (!pending) {
+    /** @type {(value: unknown) => void} */
+    let resolve = () => {};
+    /** @type {(error: Error) => void} */
+    let reject = () => {};
+    const promise = new Promise((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    promise.catch(() => {});
+    pending = { promise, resolve, reject };
+    values.set(id, pending);
+  }
+  return pending;
+}
+
+/** @param {string} renderId */
+function forgetRender(renderId) {
+  const entry = renders.get(renderId);
+  if (!entry) return;
+  clearTimeout(entry.timer);
+  renders.delete(renderId);
+}
+
+/** @param {http.IncomingMessage} req */
+async function readBody(req) {
+  /** @type {Buffer[]} */
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > MAX_BODY_BYTES) throw new Error('payload too large');
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+const server = http.createServer(async (req, res) => {
+  if (req.headers['x-netjes-token'] !== token) {
+    res.writeHead(403).end();
+    return;
+  }
+  if (req.method === 'GET' && req.url === '/health') {
+    res.writeHead(200, { 'content-type': 'text/plain' }).end('ok');
+    return;
+  }
+  if (req.method === 'POST' && req.url === '/resolve') {
+    try {
+      const { renderId, id, value, error } = JSON.parse(await readBody(req));
+      if (typeof renderId !== 'string' || typeof id !== 'string') throw new Error('renderId and id are required');
+      const pending = pendingValue(renderId, id);
+      if (typeof error === 'string') pending.reject(new Error(error));
+      else pending.resolve(value);
+      res.writeHead(204).end();
+    } catch (error) {
+      res.writeHead(400, { 'content-type': 'text/plain' }).end(error instanceof Error ? error.message : String(error));
+    }
+    return;
+  }
+  if (req.method !== 'POST' || req.url !== '/render') {
+    res.writeHead(404).end();
+    return;
+  }
+  // Stop rendering once nobody is waiting for the result: the caller went away or the time is up.
+  const controller = new AbortController();
+  // Waiting for everything (crawlers) includes the slow Suspense boundaries, so it gets the stream's time limit.
+  const waitForAll = req.headers['x-netjes-wait-all'] === '1';
+  const shellTimeoutMs = waitForAll ? streamTimeoutMs : renderTimeoutMs;
+  let timer = setTimeout(() => controller.abort(new Error(`Rendering timed out after ${shellTimeoutMs}ms`)), shellTimeoutMs);
+  res.on('close', () => {
+    if (!res.writableFinished) controller.abort(new Error('The caller stopped waiting for the render'));
+  });
+  const renderId = typeof req.headers['x-netjes-render-id'] === 'string' ? req.headers['x-netjes-render-id'] : undefined;
+  /** @type {RenderOptions} */
+  const options = { signal: controller.signal, waitForAll };
+  if (renderId) {
+    options.deferred = (id) => pendingValue(renderId, id).promise;
+    res.on('close', () => forgetRender(renderId));
+  }
+  try {
+    const data = await readBody(req);
+    if (!renderToStream) {
+      const html = await render(data, options);
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }).end(html);
+      return;
+    }
+    const stream = await renderToStream(data, options);
+    // The shell is out; what is left may take longer (Suspense boundaries), up to the stream timeout.
+    clearTimeout(timer);
+    timer = setTimeout(() => controller.abort(new Error(`Streaming timed out after ${streamTimeoutMs}ms`)), streamTimeoutMs);
+    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'x-accel-buffering': 'no' });
+    try {
+      await pipeline(stream, res);
+    } catch (error) {
+      if (!controller.signal.aborted) console.error('netjes: streaming failed', error);
+      res.destroy();
+    }
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    vite?.ssrFixStacktrace(err);
+    const message = plainText(err.message);
+    const stack = err.stack === undefined ? undefined : plainText(err.stack);
+    // The .NET span that asked for this render (W3C trace context), to find it next to the request's trace.
+    const trace = req.headers.traceparent ? ` traceparent=${req.headers.traceparent}` : '';
+    console.error(`netjes: render failed${trace}\n${stack ?? message}`);
+    if (!res.destroyed) {
+      res.writeHead(500, { 'content-type': 'application/json' }).end(JSON.stringify({ error: { message, stack } }));
+    }
+  } finally {
+    clearTimeout(timer);
+  }
+});
+
+server.listen(0, '127.0.0.1', () => {
+  const address = server.address();
+  const port = typeof address === 'object' && address ? address.port : 0;
+  const viteOrigin = vite ? (vite.config.server.origin ?? `http://localhost:${vitePort}`) : null;
+  process.stdout.write(`NETJES_READY ${JSON.stringify({ port, viteOrigin })}\n`);
+});
+
+async function shutdown() {
+  server.close();
+  await vite?.close();
+  process.exit(0);
+}
+
+// A promise rejected by page code without a handler would otherwise kill every render in flight.
+process.on('unhandledRejection', (reason) => console.error('netjes: unhandled promise rejection', reason));
+
+// The parent keeps our stdin open for as long as it lives; EOF means it is gone.
+process.stdin.on('end', shutdown);
+process.stdin.resume();
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);

package/skills/netjes/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: netjes
+description: Use when building or changing a Netjes app (React pages in app/ served by ASP.NET Core): adding pages, layouts, C# loaders, server actions, JSON endpoints, caching, streaming, tests or deployment. Covers the app/ and Features/ conventions, generated/netjes.ts, and the commands that check the work.
+---
+
+# Building a Netjes app
+
+Netjes renders React pages from ASP.NET Core. C# receives every request and owns routing, loaders, server actions, authorization and caching. A Node sidecar renders the React tree to HTML; the browser hydrates it, and later navigations fetch the next page's props as JSON from the same C# endpoints. The file conventions in `app/` are the Next.js App Router's, but there are no React Server Components and no `route.ts`: data comes from C# loaders, and APIs are minimal API endpoints.
+
+## Where things go
+
+- `app/**/page.tsx`: a page. `app/blog/[slug]/page.tsx` serves `/blog/{slug}`. Layouts, boundaries and folder rules: [references/routing.md](references/routing.md).
+- `Features/<Feature>/*.cs`: the C# side of a feature, mapped by an extension method that `Program.cs` calls before `app.MapPages()`. Loaders and actions: [references/data-and-actions.md](references/data-and-actions.md).
+- `generated/netjes.ts`: zod schemas and typed references generated from the C# types and the page files. Read it to see what a page receives; never edit it.
+- `components/`: React components and their tests. Testing: [references/testing.md](references/testing.md).
+
+## The loop for any change
+
+1. Write the failing test first: a Vitest component test, or a C# test for loader and action logic.
+2. Change the C# record, loader or action, then run `npx netjes generate` so `generated/netjes.ts` matches (a running `npm run dev` rewrites it when it restarts).
+3. Use the generated names in React: `pages['/pattern']`, `layouts['app/folder']`, `serverActions['name']`, `api['GET /api/...']`, `route('/pattern', params)`.
+4. Check: `npm test`, `npm run typecheck`, `dotnet build` (warnings are errors), `npx netjes generate --check`, and `npm run routes` for route warnings.
+
+## A page with data, end to end
+
+```csharp
+// Features/Posts/PostPages.cs
+namespace MyApp.Features.Posts;
+
+public static class PostPages
+{
+    public sealed record PostProps(string Slug, string Title, string Body);
+
+    public static void MapPostPages(this IEndpointRouteBuilder app)
+    {
+        // The parameter name matches [slug]; Page.Props names the props type for the generated schema.
+        app.MapPageLoader("/blog/[slug]", (string slug, PostStore posts) =>
+            posts.Find(slug) is { } post
+                ? Page.Props(new PostProps(post.Slug, post.Title, post.Body))
+                    .WithMetadata(new PageMetadata { Title = post.Title })
+                : Page.NotFound());
+    }
+}
+```
+
+```tsx
+// app/blog/[slug]/page.tsx
+import { Link, definePage } from 'netjes';
+import { pages, route } from '../../../generated/netjes.ts';
+
+export default definePage(pages['/blog/[slug]'], function Post({ title, body }) {
+  return (
+    <article>
+      <Link href={route('/blog')}>All posts</Link>
+      <h1>{title}</h1>
+      <p>{body}</p>
+    </article>
+  );
+});
+```
+
+`Program.cs` calls `app.MapPostPages();` before `app.MapPages();`. A page without a loader is a plain default export with no props.
+
+## Rules
+
+- Decisions live in C#: data access, validation, authorization (`.RequireAuthorization()`, `Page.Forbidden()`), redirects, caching. React renders what it is sent.
+- Loaders and actions return Netjes results (`Page.Props(...)`, `Page.NotFound()`, `ServerAction.Ok(...)`), so their types reach `generated/netjes.ts`. Use records for everything that crosses to the browser.
+- zod at every boundary: `definePage`/`defineLayout` with the generated schemas, `useSearchParams(schema)` and `useParams(schema)` (schemas at module level), `api[...].response.parse(...)` for fetched JSON, `usePublicConfig(schema)`. No `any`, no casts of server data.
+- Server state goes through TanStack Query, seeded from the loader with `.WithQuery(key, data)`; no `useEffect` fetching.
+- Internal links use `<Link>` and `route()`; forms use `<Form>` with `useAction`, and must work without JavaScript.
+- Never edit `generated/netjes.ts`; regenerate it and commit it with the change.
+- Anything in `Netjes:PublicConfig` or shared props is sent to the browser.
+- Caching, streaming and static export have sharp edges: read [references/caching-and-streaming.md](references/caching-and-streaming.md) before using `.CachePage`, `Page.Defer` or `netjes export`.
+- Shipping: [references/deployment.md](references/deployment.md).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `npm run dev` | `dotnet watch` with Vite HMR on http://localhost:5080 |
+| `npm test`, `npm run typecheck` | Vitest; strict TypeScript |
+| `npx netjes generate [--check]` | Rewrite `generated/netjes.ts`; `--check` fails when it is stale |
+| `npm run routes` (`netjes routes [--json]`) | The route table and route warnings, as ASP.NET Core sees them |
+| `npx netjes build` | Types, then the client and server bundles |
+| `npx netjes start` | Run in Production |
+| `npx netjes export [dir]` | Write the site as static HTML |
+| `npx netjes info` | Versions and a check of the project setup |
+
+## More
+
+The guides go further than these references: [routing](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/routing.md), [data loading](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/data-loading.md), [actions and forms](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/actions-and-forms.md), [metadata](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/metadata.md), [images](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/images.md), [rendering and streaming](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/rendering-and-streaming.md), [caching](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/caching.md), [security](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/security.md), [testing](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/testing.md) and [deployment](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/deployment.md), with the [React API](https://github.com/DennisVerhoeven/netjes/blob/main/docs/reference/react-api.md), the [C# API](https://github.com/DennisVerhoeven/netjes/blob/main/docs/reference/csharp-api.md) and the [options](https://github.com/DennisVerhoeven/netjes/blob/main/docs/reference/options.md) as reference.
+
+The same docs as plain text: https://raw.githubusercontent.com/DennisVerhoeven/netjes/main/llms.txt (an index) and https://raw.githubusercontent.com/DennisVerhoeven/netjes/main/llms-full.txt (everything in one file). They follow the main branch; the installed version's sources and types are in `node_modules/netjes/`.

package/skills/netjes/references/caching-and-streaming.md

@@ -0,0 +1,68 @@
+# Caching, streaming and static export
+
+## Output-cached pages
+
+```csharp
+builder.Services.AddOutputCache();
+// ...
+app.UseNetjes();
+app.UseAuthentication();
+app.UseAuthorization();
+app.UseAntiforgery();
+app.UseOutputCache();          // after UseNetjes and after UseAuthentication, so signed-in users bypass it
+
+app.MapPageLoader("/blog/[slug]", (string slug, PostStore posts) => ...)
+    .CachePage(TimeSpan.FromMinutes(5), "posts");
+```
+
+- A stored page is served to every visitor, shared props included. Cache only pages that are the same for everyone: their loaders and shared props must not depend on cookies or other per-visitor state (Netjes warns once per page when a cached render reads `Request.Cookies`). Signed-in users and requests with an `Authorization` header bypass the cache.
+- Evict from an action with `ServerAction.Ok().Revalidate("posts")` or `.RevalidatePath("/blog/hello")`, and from anywhere else (a webhook, a background job) with `IPageCache.RevalidateTagAsync(tag)` / `RevalidatePathAsync(path)`.
+- Cached pages carry no antiforgery token: forms on them fetch one first, so they need JavaScript.
+- A Content-Security-Policy is off unless the app sets one. A document with a CSP nonce is never stored, so cached pages under a policy need a hash-based one (`ContentSecurityPolicy` without `{nonce}`), and under such a policy a page must not stream.
+- Keys include the host and the full URL, case included. In production pin `AllowedHosts` and set the output cache's `SizeLimit`.
+- Pages the output cache does not store go out `Cache-Control: no-store, private`, for visitors and signed-in users alike, unless the page sets its own header.
+- Draft pages and draft redirects (a loader's `Page.Redirect` in draft mode), the client-rendered fallback, the page for a failed form post, action answers and antiforgery tokens always go out `no-store`, and without the headers a CDN reads ahead of `Cache-Control` (`CDN-Cache-Control`, any other `*-Cache-Control`, `Surrogate-Control`, `Edge-Control`, `X-Accel-Expires`), whatever the page set.
+
+## TanStack Query
+
+Netjes creates one `QueryClient` per server render and per page load. `.WithQuery(key, data)` on a loader result seeds it, so `useQuery` with that key has data on the first render and fetches nothing until the data is stale (default `staleTime` one minute). Data the browser fetched more recently is kept. After an action, `.Invalidate(key)` refetches and `.WithQuery(key, data)` sets the new value. Configure the client with `netjes({ query: { defaultOptions } })` in `vite.config.ts`.
+
+## Streaming slow data
+
+```csharp
+public sealed record TaskPageProps(TaskDetail Task, Deferred<IReadOnlyList<ActivityItem>> Activity);
+
+app.MapPageLoader("/tasks/[id]", (string id, IDbContextFactory<AppDb> contexts, HttpContext http) =>
+    Page.Props(new TaskPageProps(LoadTask(id), Page.Defer(ActivityAsync(contexts, id, http.RequestAborted)))));
+```
+
+```tsx
+// The generated schema types `activity` as a promise, validated when it arrives (deferred() from netjes/zod).
+<Suspense fallback={<p>Loading activity…</p>}>
+  <ActivityFeed activity={activity} />
+</Suspense>
+
+function ActivityFeed({ activity }: { activity: PromiseLike<ActivityItem[]> }) {
+  const items = use(activity);
+  return <ol>{items.map((item) => <li key={item.id}>{item.summary}</li>)}</ol>;
+}
+```
+
+- The shell goes out first, with `loading.tsx` or the Suspense fallback where a value is pending, and each value streams in when its task completes. Client navigations stream the same way.
+- A deferred task runs alongside the rest of the request: give it its own `DbContext`, never the request's, and pass `http.RequestAborted`. Either create one from `IDbContextFactory<T>`, as above, or use the overload that runs the work in its own DI scope, started once the page's payload is written: `Page.Defer(services => services.GetRequiredService<AppDb>().ActivityAsync(id, http.RequestAborted))`.
+- Without JavaScript, a fallback that is still pending stays. Crawlers (`CrawlerUserAgents`), apps with `StreamDocuments = false` and `netjes export` get the complete document.
+- A boundary that is ready when the shell goes out is written in place, so it shows without JavaScript too.
+
+## Static export
+
+`npx netjes export [dir]` builds, runs the app once in Production and writes every page as static HTML (default `out/`). Dynamic pages need `.StaticParams(...)` (`.StaticParams<PostStore>(s => s.All.Select(p => new { slug = p.Slug }))`, arrays for catch-all parameters); pages that need a server take `.ExcludeFromExport()`. The export fails before writing anything for a dynamic page without static params, a page with a page action, or a page that requires authorization. Exported pages navigate with full page loads and carry no antiforgery token.
+
+## Sitemap and robots
+
+`app.MapSitemap(siteUrl)` serves `/sitemap.xml` from the route table (dynamic pages through `.StaticParams`, pages that need authorization or call `.ExcludeFromSitemap()` left out) and `app.MapRobotsTxt(siteUrl, disallow)` serves `/robots.txt`.
+
+Leave `/_netjes/` out of `disallow`: `<Image>` serves every image through `/_netjes/image`, so a crawler that may not fetch it cannot index your images. The other endpoints there take posts or hand out an antiforgery token, which a crawler has no use for. Under a base path, `disallow` paths are written as given, so include the base path in them. See [Metadata](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/metadata.md).
+
+## More
+
+[Caching](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/caching.md), [Rendering and streaming](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/rendering-and-streaming.md) and [Static export](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/static-export.md) in the guides.

package/skills/netjes/references/data-and-actions.md

@@ -0,0 +1,98 @@
+# Data and actions
+
+Everything a page shows comes from C#: page loaders, layout loaders, shared props and JSON endpoints. Everything a page changes goes through C#: server actions. Their C# types become zod schemas and typed references in `generated/netjes.ts`.
+
+## Page loaders
+
+```csharp
+app.MapPageLoader("/projects/[id]", async (string id, ClaimsPrincipal user, AppDb db, CancellationToken ct) =>
+{
+    var project = await db.FindProjectAsync(id, ct);
+    if (project is null) return Page.NotFound();
+    if (!project.HasMember(user)) return Page.Forbidden();
+    return Page.Props(new ProjectProps(project.Name, project.Tasks))
+        .WithQuery(["projects", id, "stats"], await db.StatsAsync(id, ct))
+        .WithMetadata(new PageMetadata { Title = project.Name });
+});
+```
+
+- It binds like a minimal API: route values by name, services, `ClaimsPrincipal`, `HttpContext`, `CancellationToken`, `[FromQuery]`.
+- It reads no request body, so a complex type that is not a registered service needs `[AsParameters]` or a static `BindAsync`. A loader or action whose parameters minimal APIs cannot bind stops the app at startup, saying which and why. So does a loader parameter that reads the body (`[FromBody]`, `[FromForm]`, `IFormFile`): posted data belongs in a page action or a server action. A page loader stops the app too for a type that adds accepts metadata (`IAcceptsMetadata`) for itself, and must not get `.Accepts<T>()`: routing would match the page only for requests with that Content-Type, and navigations would get the not-found page. Repeated query values bind to an array (`int[] ids`); `List<int>` and `IEnumerable<int>` stop the app at startup, the latter because minimal APIs would bind it from services.
+- `Page.Props(record)` names the props type for `pages['/projects/[id]']`. `Page.NotFound()`, `Page.Forbidden()`, `Page.Unauthorized()` render the nearest boundary file; `Page.Redirect(url)` and `Page.LocalRedirect(returnUrl)` (for URLs from the request) redirect, and the client router follows them. `.WithStatus(422)` changes the status.
+- It returns a `RouteHandlerBuilder`: `.RequireAuthorization()`, `.CachePage(...)` and filters apply.
+- A page's loader runs before its layouts' loaders, so a page under a layout that checks access checks it too.
+
+## Layout loaders
+
+`app.MapLayoutLoader("/projects/[id]", ...)` loads the data of `app/.../projects/[id]/layout.tsx` (by URL, or by folder: `app/(shop)`). The layout reads it with `defineLayout(layouts['app/(app)/projects/[id]'], function Layout({ project, children }) { ... })`. Its conventions (`.RequireAuthorization()`) apply to every page below. `NotFound`/`Forbidden` from it render the nearest boundary above the layout.
+
+- It binds only the route values of its own URL (`id` here, never a deeper `taskId`; a `[FromRoute]` naming one stops the app at startup), the query string and services. Nothing binds from a body: a complex type needs to be a service, `[AsParameters]` or bind itself, and `[FromBody]`, `[FromForm]` or a file stops the app at startup.
+- On client navigations within the section it is skipped while its route values, user and roles are unchanged, so checks that must run on every request belong in conventions or page loaders, and it must not depend on the query string or cookies.
+
+## Shared props
+
+`options.UseSharedProps(http => ValueTask.FromResult(new SiteProps(...)))` in `AddNetjes` gives every page and layout the same props: `useSharedProps(sharedProps)`. Typical: the signed-in user, from `http.User`. They are sent to the browser.
+
+## Server actions
+
+```csharp
+using System.ComponentModel.DataAnnotations;
+using Microsoft.AspNetCore.Mvc; // [FromForm]: not in the implicit usings
+
+public sealed record Renamed(string Name);
+
+public sealed record RenameInput
+{
+    [Required] public string Id { get; init; } = "";
+    [Required(ErrorMessage = "Give it a name."), StringLength(100)] public string Name { get; init; } = "";
+}
+
+app.MapAction("projects.rename", async ([FromForm] RenameInput input, AppDb db, CancellationToken ct) =>
+    await db.TryRenameAsync(input.Id, input.Name, ct)
+        ? ServerAction.Ok(new Renamed(input.Name)).RevalidatePath($"/projects/{input.Id}")
+        : ServerAction.Invalid("name", "That name is taken."));
+```
+
+```tsx
+const [state, formAction, pending] = useAction(serverActions['projects.rename']);
+const nameError = state?.ok === false ? state.errors.name?.[0] : undefined;
+
+<Form action={formAction}>
+  <input type="hidden" name="id" value={id} />
+  <input name="name" defaultValue={state?.ok === false ? String(state.values?.name ?? '') : name} aria-invalid={nameError ? true : undefined} />
+  {nameError && <p>{nameError}</p>}
+  <button disabled={pending}>Rename</button>
+</Form>
+```
+
+- Results: `ServerAction.Ok(result)` or `Ok()`, `Invalid(field, message)` or `Invalid(errors)` (422), `Redirect(url)`, `Forbidden()`, `NotFound()`. Chain `.Revalidate(tags)` and `.RevalidatePath(paths)` (evict output-cached pages and refresh the page), `.Refresh()`, `.Invalidate(queryKey)` and `.WithQuery(queryKey, data)` (TanStack Query on the client).
+- `[FromForm]` inputs make the form work without JavaScript: the browser posts, a success redirects back, a failure renders the page again with the errors and the typed values. Keep that working.
+- An input without `[FromForm]` binds JSON: `await serverActions['posts.like']({ slug })` resolves to `{ ok: true, result }` or `{ ok: false, errors }`; server failures throw to the nearest error boundary.
+- Validation: DataAnnotations (`[Required]`, `[StringLength]`, `[Range]`, `[EmailAddress]`) and `IValidatableObject` on an action's input are checked before the action runs (for a polymorphic JSON input, those of the `[JsonDerivedType]` the call sends). Failures come back as field errors (422, `state.errors`), also without JavaScript, and the action is not called. This needs no setup: `builder.Services.AddValidation()` is for your other minimal API endpoints, not for `MapAction` or `MapPageAction`. An attribute that cannot be read, such as a `[Display]` whose resource type has no such name, stops the app at startup, also on a derived type a JSON input lists with `[JsonDerivedType]`. A `[FromForm]` input is never `null` (unless declared nullable): a post with none of its fields, such as a form of unchecked checkboxes, gets an empty input, checked like any other. Give form inputs `init` properties, as above, not constructor parameters: a field the post leaves out (an unchecked checkbox, a list with nothing chosen) keeps its default, while form binding refuses such a post (400) for a positional record. A form input, and each type its properties and lists hold, needs exactly one public constructor: form binding never builds a type with several or none, or an abstract class or an interface, so that stops the app at startup. Bind a checkbox group or a list as a property of the input type (`public string[] Tags { get; init; } = [];`), not as a top-level `[FromForm]` parameter: a top-level list or dictionary reads fields named `[0]` or `[key]`, not its own name, and is `null` when none is posted.
+- Optimistic UI: `useAction(action, { onSubmit(formData) { setOptimistic(...) } })` with React's `useOptimistic`.
+- Every action needs `app.UseAntiforgery()` (after authentication) and checks the origin; `<Form>` and `serverActions` send the token. `MapAction` bodies are limited to 1 MB (`ActionBodySizeLimit`); an upload action sets `[RequestSizeLimit(bytes)]`. Page actions keep the server's limit.
+- Name actions `feature.verb`. Check authorization inside the action, or with `.RequireAuthorization()`, as for any endpoint.
+- `app.MapPageAction("/guestbook", ...)` is the other kind: a POST to the page's own URL from `<Form method="post">`, fields typed in `forms['/guestbook']`. Its input's DataAnnotations and `IValidatableObject` are checked as for `MapAction`: on a failure the delegate does not run, the page renders again from its loader (422), and `const failed = usePageActionState()` gives `failed.errors` and `failed.values` (null otherwise). Checks that need data stay in the delegate: return `Page.Props(...)` with your own errors and the typed values (`.WithStatus(422)`), or `Page.Redirect(...)` after a change.
+- An action or post that sets or deletes a cookie (signing in or out) makes the client router forget the pages it keeps for back and forward, reload the page on screen and clear the query cache, in every tab of the app in that browser. Nothing to do in the action; a proxy must pass `X-Netjes-Cookies` through.
+
+## JSON endpoints and TanStack Query
+
+```csharp
+app.MapGet("/api/projects/{slug}/stats", async Task<Results<Ok<ProjectStats>, NotFound>> (string slug, AppDb db) => ...)
+    .RequireAuthorization();
+```
+
+```ts
+async function fetchStats(slug: string) {
+  const response = await fetch(`/api/projects/${encodeURIComponent(slug)}/stats`);
+  if (!response.ok) throw new Error(`Stats request failed with ${response.status}`);
+  return api['GET /api/projects/{slug}/stats'].response.parse(await response.json());
+}
+const stats = useQuery({ queryKey: ['projects', slug, 'stats'], queryFn: () => fetchStats(slug) });
+```
+
+Typed results (`TypedResults`, `Results<...>`) give the endpoint its `api` schemas, keyed by method and route template. Seed the same query key from the loader with `.WithQuery(key, data)` and the query renders on the server with no fetch; keep the key in one place on each side. Seeded data is fresh for the default `staleTime` (one minute).
+
+## More
+
+[Data loading](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/data-loading.md) and [Actions and forms](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/actions-and-forms.md) in the guides.

package/skills/netjes/references/deployment.md

@@ -0,0 +1,57 @@
+# Deployment
+
+A Netjes app is an ASP.NET Core app that also needs Node at runtime: the .NET process starts and supervises the Node sidecar that renders pages (`NetjesOptions.NodeExecutable`, default `node` on the `PATH`). Only `netjes export` output runs without either.
+
+## Build and publish
+
+```bash
+npx netjes generate --check   # in CI: the generated types match the C# types
+npm test && npm run typecheck && dotnet build
+dotnet publish -c Release -o bin/publish   # runs `npm run build`, ships dist/ (client, server bundle, sidecar)
+cd bin/publish && ASPNETCORE_ENVIRONMENT=Production dotnet MyApp.dll
+```
+
+`npx netjes start` runs the app in Production from the source tree (or `--dll bin/publish/MyApp.dll`, which runs from the publish folder). In production the routes come from the built client manifest, so a page file that was not built does not exist.
+
+For these startup failures the app logs one critical entry, saying what is wrong and what to do, and exits with code 1: no build in Production (`npm run build`), a `node` it cannot start (`Netjes:NodeExecutable`), a sidecar script that is not installed or built (`npm install` in development, `npm run build` in production), or in development the Vite dev server's port taken, an error in `vite.config.ts` (with Vite's code frame) or a package it imports that is not installed (`npm install`). Under `WebApplicationFactory` the start throws that message instead. Other exceptions at startup, such as a route conflict, keep their stack.
+
+## Docker
+
+`netjes new` writes a `Dockerfile` and Compose files:
+
+- `docker compose up`: development, with `dotnet watch` and Vite HMR, ports bound to localhost.
+- `docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d`: the production image, a non-root user on a read-only filesystem, with a health check on `/healthz` and Data Protection keys in a named volume.
+
+The image restores Netjes from NuGet and npm, so the app must reference the packages, as an app made with `npx netjes new` does (from a Netjes checkout, pass `--packages`).
+
+## Production settings
+
+- `AllowedHosts`: pin it to the site's host names. `appsettings.Development.json` already limits Development to loopback names.
+- HTTPS: outside Development the template calls `UseHsts()` and `UseHttpsRedirection()`. Behind a proxy that terminates TLS, call `UseForwardedHeaders()` first, trusting only that proxy's network (`KnownIPNetworks`), so the app sees https and the visitor's address.
+- Data Protection keys sign antiforgery tokens and draft-mode cookies: keep them across restarts (the production compose file mounts a volume) and share them between instances.
+- Several instances behind a load balancer also share the output-cache store and need the same `Netjes:SegmentKeySecret` (32 bytes or more).
+- `Netjes:SidecarProcesses`: Node processes rendering in production (default 1; about one per core for CPU-heavy pages).
+- If no sidecar is ready (they crashed and are restarting), documents are sent for the browser to render instead of failing (`ClientRenderFallback`, on by default), and `/healthz` reports Unhealthy. Register the check with `builder.Services.AddHealthChecks().AddNetjes()` and `app.MapHealthChecks("/healthz")`.
+- Output caching: set `SizeLimit`, and see [caching-and-streaming.md](caching-and-streaming.md).
+- Security headers: every document gets `X-Content-Type-Options`, `Referrer-Policy` and a same-origin framing policy unless the app sets them (`Netjes:SecurityHeaders`). A Content-Security-Policy is off until you set `NetjesOptions.ContentSecurityPolicy`, with `{nonce}` for a nonce-based policy.
+- `Netjes:PublicConfig` is sent to the browser as is; secrets go in other configuration.
+- Telemetry: add the `Netjes` ActivitySource and Meter (`NetjesTelemetry.Name`) to OpenTelemetry for loader, action and render spans and render durations.
+
+## Startup work and CLI commands
+
+`netjes generate` and `netjes routes` run the app once in command mode, without serving or starting Node. Skip startup work they do not need, such as migrations or seeding:
+
+```csharp
+if (app.GetNetjesCommand() is null)
+{
+    await SeedAsync(app.Services);
+}
+```
+
+## Static hosting
+
+`npx netjes export` writes the site as static HTML to `out/` for any static host; see [caching-and-streaming.md](caching-and-streaming.md#static-export) for what it needs and refuses.
+
+## More
+
+[Deployment](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/deployment.md) and [Security](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/security.md) in the guides, and every option in [Options](https://github.com/DennisVerhoeven/netjes/blob/main/docs/reference/options.md).