@stopnetic/js 0.0.5-pilot → 0.0.6-pilot

package/README.md

@@ -6,18 +6,21 @@ frontend build. No React/Vue/Angular dependency or version upgrade is required.
 The hosting server must run Node.js 22 or newer. This is an MIT-licensed pilot SDK;
 hosted production/provider validation is still required before paid rollout.
 
-Version **0.0.5-pilot is prepared locally; it is not published yet**. The guide
-offers two explicit rendering paths: preserve SSR or retain a static/CSR app.
-Server document navigation is the default; leave startup/layout unchanged with
-no global checking screen. Optional SPA demos for all six frontends explain
-their asynchronous checks and use empty pending content. Unchanged
-0.0.2/0.0.3/0.0.4 guides migrate safely; custom edits require merging.
+Version **0.0.6-pilot is prepared locally; it is not published yet**. It adds
+framework-specific SSR instructions and a dashboard SSR selector for Angular,
+React Router, custom React SSR, Nuxt, custom Vue SSR, SvelteKit, Astro, SolidStart
+and custom Node servers. Examples identify the actual server entry, prerender
+settings, deployed Node runtime and context/body preservation. Next.js uses its
+dedicated adapter; other languages/Edge are explicitly outside this Node SDK.
+Unchanged 0.0.2/0.0.3/0.0.4/0.0.5 guides migrate safely; custom edits require merging.
+SSR and static rendering remain separate choices, with document navigation
+default and no global checking screen. Optional browser demos remain available.
 Angular, React, Vue, Svelte, Solid and plain JavaScript share the browser/server
 contracts; no React dependency is required. See the
 [complete generated guide](dist/client-guide.md) for SSR, static builds, frameworks,
 client navigation, API protection and runtime restrictions.
 
-The currently published **0.0.4-pilot** includes full frontend examples and the
+The currently published **0.0.5-pilot** clarifies rendering/navigation and includes full frontend examples and the
 framework-independent server/browser setup, complete Node application wrapper
 and older-guide migration. Version 0.0.2 added the reusable browser/server setup for Netlify, Vercel
 and Node/Express, a browser access check and optional React boundary. It also
@@ -30,6 +33,36 @@ npm install @stopnetic/js@pilot
 
 ## Framework implementation examples
 
+SSR apps use the **SSR framework** selector, not the optional browser-demo
+selector. [Framework SSR instructions](dist/client-guide.md#ssr-framework-instructions)
+and `examples/ssr` contain matching server code:
+
+| SSR app | Server connection |
+| --- | --- |
+| Angular | AngularAppEngine Fetch entry or Express before AngularNodeAppEngine |
+| React Router | Existing Express entry; single-fetch `.data` aliases use page policy |
+| Custom React / Vue | Guard before the existing Node renderer; keep hydration |
+| Nuxt 3/4 (Nitro 2/H3 1) | Root Node server middleware before rendering/APIs |
+| SvelteKit | `handle` before `resolve(event)`; canonical page check for data requests |
+| Astro | `onRequest` before `next()` with an existing Node adapter |
+| SolidStart 1 / 2 | Version-specific request middleware before continuation |
+| Custom Node / plain JavaScript | Root Express middleware or complete Fetch wrapper |
+| Next.js | Dedicated `@stopnetic/next` guide |
+
+Merge existing files/context, preserve public routes and keep protected output
+out of prerender/static/CDN caches. These manual snippets are not automatic
+framework installers. Node compatibility does not validate a live provider.
+Only dashboard rules decide verification; Angular-specific flags are not instructions
+for other frameworks. React/Vue libraries without a server use the static option.
+
+To test server continuation contracts after `npm run build`, run
+`node tests/prepare-ssr-guide-tests.mjs`, then `node tests/ssr-guide-check.mjs`.
+Dependencies remain in ignored test-results. Native H3 1/2 and Express exercise
+signed access, control isolation, data aliases and unread POST bodies. Astro,
+SvelteKit and SolidStart factory imports use contract shims, not full framework
+builds. Angular's separate fixture compiles/renders real SSR. Live routing,
+prerender/cache behavior and complete framework/provider builds still need validation.
+
 The guide and `examples/frontend` contain complete, locally tested OPTIONAL
 browser-only SPA examples. The default document-navigation integration needs
 the server guard and normal links, not these full-layout browser gates. Keep SSR
@@ -71,7 +104,7 @@ npm run build
 npm pack
 ```
 
-Install the resulting `stopnetic-js-0.0.5-pilot.tgz` into the website project using
+Install the resulting `stopnetic-js-0.0.6-pilot.tgz` into the website project using
 `npm install <absolute-path-to-tarball>`. The installed package has no Next.js or
 other runtime dependency. The build packages the same signed decision implementation
 as the Next.js adapter. Keep `@stopnetic/next` for its Next.js 16 guided installer.

package/dist/client-guide.md

@@ -2,9 +2,11 @@
 
 Angular, React, Vue, Svelte, Solid and plain JavaScript use the same server guard
 and browser access check. React is optional. Install `@stopnetic/js` in the
-website project; choose a hosting platform, not a frontend framework.
+website project. The CLI chooses hosting files; choose your actual SSR framework
+in the instructions below to see where its server guard belongs.
 
-Jump to your implementation: [React Router](#react-router),
+Start with [SSR framework instructions](#ssr-framework-instructions) if the app
+renders on the server. Optional browser-only demos: [React Router](#react-router),
 [Angular Router](#angular-router), [Vue Router](#vue-router),
 [Svelte](#svelte-navigation), [Solid Router](#solid-router),
 [plain JavaScript](#plain-javascript-navigation). Each section includes the
@@ -148,11 +150,57 @@ the shared guard before its `resolve`, `next` or renderer. A Fetch wrapper is
 for a complete handler returning a Response, not every framework middleware
 signature. Node/Express can mount the generated helper around any renderer.
 
+<!-- BEGIN SSR EXAMPLES -->
+
+### SSR framework instructions
+
+Choose the actual SSR framework, not just the browser UI library. Angular
+instructions apply ONLY to Angular. Each section below identifies the server
+file, integration steps, prerender constraints and runtime. The same sections
+appear in the dashboard SSR framework selector. Merge examples into existing
+entries; do not replace SSR, hydration, context or application features.
+
+Use your selected framework hook OR the shared Node wrapper above. Do not
+stack both or mount the generated Express helper as an additional guard.
+
+| Your app | Choose |
+| --- | --- |
+| Angular with SSR | Angular SSR |
+| React Router framework/server mode | React Router SSR |
+| React plus your own Node renderer | React custom SSR |
+| Nuxt | Nuxt (Vue SSR) |
+| Vue plus your own Node renderer | Vue custom SSR |
+| SvelteKit | SvelteKit SSR |
+| Astro on-demand rendering | Astro SSR |
+| SolidStart | SolidStart SSR; match the installed major version |
+| Other Node renderer / plain JavaScript server | Other Node SSR |
+| Next.js | Dedicated @stopnetic/next guide; do not install the JS control files |
+| React/Vue/Svelte/Solid UI without an SSR server | Option B: static/browser app |
+| PHP, Python, Ruby, C#, Java or Edge/Deno | No native adapter in this Node npm SDK; a separate runtime adapter/gateway is needed |
+
+All snippets require SDK 0.0.3-pilot or newer and six SERVER settings. They
+are manual integration examples, not automatic installers for each framework.
+Validate the actual deployed adapter, versions, internal data endpoints and
+cache/static aliases. Hook-contract checks do not prove provider deployment.
+
 ### Angular SSR on Node
 
-For a Fetch-style Angular SSR entry in `src/server.ts`:
+**Where:** src/server.ts (Fetch entry), or your existing Express server.ts before AngularNodeAppEngine.handle.
+
+1. Keep server.ts, main.server.ts, server providers, host configuration and hydration. Merge the guard into the existing request entry; preserve extra framework context.
+2. Use the Fetch example only for an AngularAppEngine Request/Response entry. An Express entry instead mounts the Node helper before express.static and AngularNodeAppEngine.handle.
+3. Protected paths use RenderMode.Server. The wildcard below is an example, not a replacement for existing public/hybrid route configuration.
+
+**Prerendering and caches:** Do not publish protected RenderMode.Prerender output to a public CDN. Retain public rendering modes only where they cannot bypass future protection. Any path the dashboard may protect must reach the server guard before HTML.
+
+**Hosting runtime:** Node.js 22+ only. Keep the existing Node hosting adapter; check the deployed runtime, not just the hosting brand. Edge/Deno deployments need a separate supported adapter or a gateway decision. Do not convert SSR to static rendering automatically.
+
+**Netlify Angular only:** Netlify’s automatic Angular SSR uses Edge Functions. The current Node SDK has no drop-in integration for that combination. Keep SSR; obtain a supported Node deployment or gateway decision. A static index.html function is not an Angular SSR adapter.
+
+#### src/server.ts
 
 ```ts
+// Merge into your existing Node SSR entry; retain host settings and context.
 import { AngularAppEngine, createRequestHandler } from '@angular/ssr';
 import { createStopneticAppHandler } from '@stopnetic/js/server';
 
@@ -166,36 +214,364 @@ async function handle(request: Request): Promise<Response> {
 export const reqHandler = createRequestHandler(handle);
 ```
 
-Keep existing Angular host configuration and request context if your entry
-uses them. For an Express-based Angular entry, mount `installStopnetic(app)`
-before `express.static` and `AngularNodeAppEngine.handle` instead.
-
-Protected routes in `src/app/app.routes.server.ts` must use request-time
-rendering rather than `RenderMode.Prerender`:
+#### src/app/app.routes.server.ts
 
 ```ts
 import { RenderMode, ServerRoute } from '@angular/ssr';
 export const serverRoutes: ServerRoute[] = [
-  // All routes are rendered on incoming requests in this example.
+  // Demo only: merge with existing hybrid modes rather than replacing them.
   { path: '**', renderMode: RenderMode.Server },
 ];
 ```
 
-This is an all-request-time demonstration, not an instruction to replace an
-existing hybrid route configuration. Preserve public rendering modes where
-appropriate. Any path the dashboard may protect must reach the guard before
-HTML is served; publicly cached/prerendered HTML bypassing it cannot be protected
-by adding a dashboard rule alone. Plan server coverage for those paths first.
+Framework references: [Angular SSR](https://angular.dev/guide/ssr), [Netlify Angular runtime](https://docs.netlify.com/build/frameworks/framework-setup-guides/angular/).
+
+### React Router framework mode on Node
+
+**Where:** Existing Express entry before @react-router/express createRequestHandler.
+
+1. React Router framework mode supplies the SSR server. Keep its server build, loaders/actions, getLoadContext and hydration; BrowserRouter alone is not an SSR backend.
+2. Copy the helper, then import and call it at the application root before parsers/assets and the existing createRequestHandler. Do not place it after the renderer or mount it at a stripped URL prefix.
+3. The helper checks React Router 7 .data requests against their page path, including /_root.data. The actual router still receives its original URL and unread body. This example uses the default / basename; custom basenames and other router versions need alias mapping review.
+
+**Prerendering and caches:** Keep ssr enabled in react-router.config.ts. Exclude protected paths from prerender output and CDN caches. Direct .data requests must not expose private loaders merely because the document path is guarded. Independently authorize resource routes, actions and server functions.
+
+**Hosting runtime:** Node.js 22+ only. Keep the existing Node hosting adapter; check the deployed runtime, not just the hosting brand. Edge/Deno deployments need a separate supported adapter or a gateway decision. Do not convert SSR to static rendering automatically.
+
+#### stopnetic-react-router.mjs
+
+```js
+// Call installStopneticReactRouter(app) before parsers, assets and the existing
+// @react-router/express createRequestHandler. Keep that handler/context intact.
+import { createStopneticServer } from '@stopnetic/js/server';
+
+export function installStopneticReactRouter(app) {
+  let server;
+  app.use((req, res, next) => {
+    server ??= createStopneticServer();
+    return server.access(req, res, () => {
+      // React Router 7 single-fetch data URLs must use the page's policy.
+      // The renderer still receives the original request and unread body.
+      const url = new URL(req.originalUrl || req.url, 'https://example.invalid');
+      let checked = req;
+      if (url.pathname.endsWith('.data')) {
+        url.pathname = url.pathname === '/_root.data' ? '/' : url.pathname.slice(0, -5);
+        checked = Object.create(req);
+        checked.originalUrl = url.pathname + url.search;
+      }
+      return server.guard(checked, res, next);
+    });
+  });
+}
+```
+
+#### Existing Express entry (merge fragment)
+
+```js
+// In your EXISTING Express entry, before parsers, static files and rendering:
+import { installStopneticReactRouter } from './stopnetic-react-router.mjs';
+installStopneticReactRouter(app);
+// Keep the existing renderer, application routes and server startup below.
+```
+
+Framework references: [React Router server adapters](https://reactrouter.com/api/other-api/adapter), [React Router prerendering](https://reactrouter.com/how-to/pre-rendering).
+
+### React with an existing custom SSR server
+
+**Where:** Existing Node/Express server before React rendering and any private data handler.
+
+1. React is a UI library; this option assumes you already have a Node SSR server. Keep renderToPipeableStream/renderToReadableStream, request context and hydrateRoot.
+2. Copy the helper and call it before the existing assets/API/renderer middleware. For a Fetch-style server use the custom Node Fetch wrapper instead.
+3. A Vite React SPA without a server uses Option B: static/browser app. Next.js and React Router SSR have their own selector entries. Do not add a second renderer or replace the app with the browser demo.
+
+**Prerendering and caches:** Do not statically publish protected HTML or embed private data in public bundles. Keep guarded rendering at request time, retaining public prerendering only with correct server/CDN coverage.
+
+**Hosting runtime:** Node.js 22+ only. Keep the existing Node hosting adapter; check the deployed runtime, not just the hosting brand. Edge/Deno deployments need a separate supported adapter or a gateway decision. Do not convert SSR to static rendering automatically.
+
+#### stopnetic-react-ssr.mjs
+
+```js
+// Existing custom React SSR server: call before assets, APIs and React rendering.
+// Keep renderToPipeableStream/renderToReadableStream and hydration unchanged.
+import { createStopneticServer } from '@stopnetic/js/server';
+export function installStopneticReactSSR(app) {
+  let server;
+  app.use((req, res, next) => {
+    server ??= createStopneticServer();
+    return server.access(req, res, () => server.guard(req, res, next));
+  });
+}
+```
+
+#### Existing Express entry (merge fragment)
+
+```js
+// In your EXISTING Express entry, before parsers, static files and rendering:
+import { installStopneticReactSSR } from './stopnetic-react-ssr.mjs';
+installStopneticReactSSR(app);
+// Keep the existing renderer, application routes and server startup below.
+```
+
+Framework references: [React Node SSR](https://react.dev/reference/react-dom/server/renderToPipeableStream).
+
+### Nuxt 3/4 with Nitro 2 and H3 1 on Node
+
+**Where:** server/middleware/00-stopnetic.mjs; runs before Nitro renders pages and serves API handlers.
+
+1. Keep Nuxt SSR, its app, pages, hydration and existing Node Nitro preset. Check the installed Nitro/H3 versions; this example uses H3 1 fromNodeMiddleware, not the H3 2 API.
+2. Add this server middleware before other body readers and handlers. app/middleware and defineNuxtRouteMiddleware are navigation UI hooks and cannot replace this server guard.
+3. Keep the private environment settings in the deployed Node process. Do not use runtimeConfig.public. Test the built server and separate provider functions, not only Nuxt dev.
+
+**Prerendering and caches:** Do not use nuxt generate or prerender/SWR/ISR/cached route rules for protected paths. Protected _payload.json files must not be generated into public output. Keep public route rules only where they cannot expose protected content through CDN/cache aliases.
+
+**Hosting runtime:** Node.js 22+ only. Keep the existing Node hosting adapter; check the deployed runtime, not just the hosting brand. Edge/Deno deployments need a separate supported adapter or a gateway decision. Do not convert SSR to static rendering automatically.
+
+#### server/middleware/00-stopnetic.mjs
+
+```js
+// server/middleware/00-stopnetic.mjs. Nuxt 3/4, Nitro 2, H3 1, NODE only.
+// Use server middleware, not app/middleware or defineNuxtRouteMiddleware.
+import { fromNodeMiddleware } from 'h3';
+import { createStopneticServer } from '@stopnetic/js/server';
+
+let server;
+export default fromNodeMiddleware((req, res, next) => {
+  server ??= createStopneticServer();
+  return server.access(req, res, () => server.guard(req, res, next));
+});
+```
+
+Framework references: [Nuxt server middleware](https://nuxt.com/docs/4.x/directory-structure/server), [H3 1 Node middleware adapter](https://v1.h3.dev/examples/from-expressjs-to-h3).
+
+### Vue with an existing custom SSR server
+
+**Where:** Existing Node/Express server before Vue rendering and private APIs.
+
+1. Vue alone is a UI library. Keep the existing createSSRApp/renderToString server, request context and client hydration.
+2. Copy and mount the helper before the existing parsers/assets/API/renderer middleware. For a Request/Response server use the custom Node Fetch wrapper.
+3. A Vue SPA uses Option B. A Nuxt app uses the Nuxt entry; do not replace either with a newly invented Express renderer.
+
+**Prerendering and caches:** Protected HTML and private serialized state must be produced only after the server check. Avoid publicly cached/prerendered output for protected paths.
+
+**Hosting runtime:** Node.js 22+ only. Keep the existing Node hosting adapter; check the deployed runtime, not just the hosting brand. Edge/Deno deployments need a separate supported adapter or a gateway decision. Do not convert SSR to static rendering automatically.
+
+#### stopnetic-vue-ssr.mjs
+
+```js
+// Existing custom Vue SSR server: call before assets, APIs and Vue rendering.
+// Keep createSSRApp/renderToString and client hydration unchanged.
+import { createStopneticServer } from '@stopnetic/js/server';
+export function installStopneticVueSSR(app) {
+  let server;
+  app.use((req, res, next) => {
+    server ??= createStopneticServer();
+    return server.access(req, res, () => server.guard(req, res, next));
+  });
+}
+```
+
+#### Existing Express entry (merge fragment)
+
+```js
+// In your EXISTING Express entry, before parsers, static files and rendering:
+import { installStopneticVueSSR } from './stopnetic-vue-ssr.mjs';
+installStopneticVueSSR(app);
+// Keep the existing renderer, application routes and server startup below.
+```
+
+Framework references: [Vue SSR](https://vuejs.org/guide/scaling-up/ssr.html).
+
+### SvelteKit server hooks on Node
+
+**Where:** src/hooks.server.js, before resolve(event) and any existing application hooks.
+
+1. Keep the existing Node adapter, SSR pages, loads/actions and hydration. Merge this handle into existing hooks; put Stopnetic first and retain other hooks in its continuation.
+2. The guard receives the original request and per-request continuation. Data requests are checked against event.url, the canonical page path, then resolve receives the original event and body.
+3. Merge prerender=false into each protected +page.server.js or a covering server layout. building skips runtime enforcement only during build; no protected path may be prerendered. Test with the full adapter server.
+
+**Prerendering and caches:** Keep SSR enabled. The runtime handle hook does not protect files already served statically. Exclude protected routes from prerender output, including __data.json. Do not rely on a page rule alone for separately exposed endpoints or remote functions.
+
+**Hosting runtime:** Node.js 22+ only. Keep the existing Node hosting adapter; check the deployed runtime, not just the hosting brand. Edge/Deno deployments need a separate supported adapter or a gateway decision. Do not convert SSR to static rendering automatically.
+
+#### src/hooks.server.js
+
+```js
+import { building } from '$app/environment';
+import { createStopneticAppHandler } from '@stopnetic/js/server';
+
+let guarded;
+// When merging existing hooks, run this first and put them in the continuation.
+export async function handle({ event, resolve }) {
+  // Build-time public prerendering only. Protected routes must have prerender=false.
+  if (building) return resolve(event);
+  guarded ??= createStopneticAppHandler((_request, run) => run());
+  // SvelteKit exposes the canonical page URL on data requests. Check that page
+  // rather than allowing an unmatched /members/__data.json alias through.
+  const checked = event.isDataRequest
+    ? new Request(event.url, { method: event.request.method, headers: event.request.headers })
+    : event.request;
+  return guarded(checked, () => resolve(event));
+}
+```
+
+#### src/routes/members/+page.server.js (merge example)
+
+```js
+// Merge into the PROTECTED route's +page.server.js, retaining loads/actions.
+export const prerender = false;
+export const ssr = true;
+```
+
+Framework references: [SvelteKit server hooks](https://svelte.dev/docs/kit/hooks), [SvelteKit page options](https://svelte.dev/docs/kit/page-options).
+
+### Astro request middleware on Node
+
+**Where:** src/middleware.js, before next() renders a page or executes an endpoint.
+
+1. Keep the existing compatible Node adapter and Astro renderer. If middleware exists, merge/sequence this guard first, preserving locals and the existing continuation.
+2. Use context.request and next(), not a browser startup gate. The isPrerendered branch is build-only public rendering; protected pages must never enter it.
+3. Set prerender=false on protected .astro pages/endpoints. Keep their existing content. For @astrojs/node middleware mode, an outer Express guard before static files is also available; do not install both patterns unnecessarily.
+
+**Prerendering and caches:** Protected pages need on-demand rendering with a Node adapter. Public prerendered pages can remain public, but files bypassing request middleware cannot acquire protection through a dashboard rule alone.
+
+**Hosting runtime:** Node.js 22+ only. Keep the existing Node hosting adapter; check the deployed runtime, not just the hosting brand. Edge/Deno deployments need a separate supported adapter or a gateway decision. Do not convert SSR to static rendering automatically.
+
+#### src/middleware.js
+
+```js
+// src/middleware.js. Keep the existing Node deployment adapter.
+import { defineMiddleware } from 'astro:middleware';
+import { createStopneticAppHandler } from '@stopnetic/js/server';
+
+let guarded;
+export const onRequest = defineMiddleware(async (context, next) => {
+  // Public prerender builds only; protected pages must export prerender=false.
+  if (context.isPrerendered) return next();
+  guarded ??= createStopneticAppHandler((_request, run) => run());
+  return guarded(context.request, () => next());
+});
+```
+
+#### src/pages/members.astro (frontmatter flag)
+
+```astro
+---
+// Merge this flag into a protected page, preserving its existing content.
+export const prerender = false;
+---
+```
+
+Framework references: [Astro middleware](https://docs.astro.build/en/guides/middleware/), [Astro Node adapter](https://docs.astro.build/en/guides/integrations-guide/node/).
+
+### SolidStart request middleware on Node
+
+**Where:** src/middleware.js, registered in the existing SolidStart config before rendering and API execution.
+
+1. Choose the snippet matching your installed major version. SolidStart 2 uses createMiddleware([...]) and H3 event.req/event.res; SolidStart 1 uses onRequest and event.request/event.response.
+2. For v2 register solidStart({ middleware: "./src/middleware.js" }) in existing vite.config.ts. For v1 register middleware in existing defineConfig in app.config.ts. Keep all other settings and the SSR entry-server.tsx.
+3. A per-request allowed marker distinguishes an authorized continuation from a verification 204. The framework continues only when the marker is set; no renderer runs on challenge/block/outage. Server functions still require their own permissions and policy checks for their actual endpoint paths.
+
+**Prerendering and caches:** Keep SSR enabled and protected routes out of prerender/static/ISR output. Use the existing Node server plugin/preset; do not assume a middleware export changes an Edge deployment into Node.
+
+**Hosting runtime:** Node.js 22+ only. Keep the existing Node hosting adapter; check the deployed runtime, not just the hosting brand. Edge/Deno deployments need a separate supported adapter or a gateway decision. Do not convert SSR to static rendering automatically.
+
+#### src/middleware.js — SolidStart 2
+
+```js
+// SolidStart 2: register this module using solidStart({ middleware: ... }).
+import { createMiddleware } from '@solidjs/start/middleware';
+import { createStopneticAppHandler } from '@stopnetic/js/server';
+
+let check;
+export default createMiddleware([
+  async (event, next) => {
+    check ??= createStopneticAppHandler((_request, state) => {
+      state.allowed = true;
+      return new Response(null, { status: 204 });
+    });
+    // Per-request state: a verification 204 must NEVER be mistaken for permission.
+    const state = { allowed: false };
+    const response = await check(event.req, state);
+    if (!state.allowed) return response;
+    event.res.headers.set('cache-control', 'private, no-store');
+    const result = await next(); // Preserve H3/SolidStart context and raw results.
+    if (!(result instanceof Response)) return result;
+    const headers = new Headers(result.headers);
+    headers.set('cache-control', 'private, no-store');
+    return new Response(result.body, {
+      status: result.status, statusText: result.statusText, headers,
+    });
+  },
+]);
+```
+
+#### src/middleware.js — SolidStart 1 alternative
+
+```js
+// SolidStart 1: register using defineConfig({ middleware: './src/middleware.js' }).
+// Keep the existing entry-server.tsx renderer. This is NOT SolidStart 2 config.
+import { createMiddleware } from '@solidjs/start/middleware';
+import { createStopneticAppHandler } from '@stopnetic/js/server';
+
+let check;
+export default createMiddleware({
+  onRequest: async event => {
+    check ??= createStopneticAppHandler((_request, state) => {
+      state.allowed = true;
+      return new Response(null, { status: 204 });
+    });
+    const state = { allowed: false };
+    const response = await check(event.request, state);
+    if (!state.allowed) return response;
+    event.response.headers.set('cache-control', 'private, no-store');
+    // undefined continues to SolidStart; preserve its rendering and API handling.
+  },
+});
+```
+
+Framework references: [SolidStart 2 middleware](https://docs.solidjs.com/solid-start/v2/reference/server/create-middleware), [SolidStart 1 middleware](https://docs.solidjs.com/solid-start/v1/reference/server/create-middleware).
+
+### Custom Node SSR or plain JavaScript server
+
+**Where:** Existing root request entry, before static HTML, API data or rendering.
+
+1. Use the Express helper OR the Fetch wrapper according to the existing server signature. Do not replace the renderer or introduce a second server.
+2. Call installStopneticSSR(app) first for Express. For Fetch, export the protected version of the existing handler using protectSSR(renderApplication); all context arguments are retained.
+3. Keep the canonical Host and private environment in the Node service. Only expose the guarded entry. Independently guard separately deployed API functions.
+
+**Prerendering and caches:** Static HTML/cache aliases must not bypass the guard. Preserve existing public routes and apply protection only through dashboard policies.
+
+**Hosting runtime:** Node.js 22+ only. Keep the existing Node hosting adapter; check the deployed runtime, not just the hosting brand. Edge/Deno deployments need a separate supported adapter or a gateway decision. Do not convert SSR to static rendering automatically.
+
+#### stopnetic-ssr.mjs
+
+```js
+// Call before parsers, static files, APIs and your existing Node SSR renderer.
+import { createStopneticServer } from '@stopnetic/js/server';
+export function installStopneticSSR(app) {
+  let server;
+  app.use((req, res, next) => {
+    server ??= createStopneticServer();
+    return server.access(req, res, () => server.guard(req, res, next));
+  });
+}
+```
+
+#### stopnetic-fetch-ssr.mjs
+
+```js
+// Wrap your existing Node Request -> Response renderer; retain all context.
+import { createStopneticAppHandler } from '@stopnetic/js/server';
+export function protectSSR(renderApplication) {
+  let guarded;
+  return (request, ...context) => {
+    guarded ??= createStopneticAppHandler(renderApplication);
+    return guarded(request, ...context);
+  };
+}
+```
 
-Netlify's automatic Angular SSR adapter currently uses Edge Functions. This
-combination does not have a drop-in integration with the current Node SDK.
-Do not import the SDK into that Edge entry or assume a Node function intercepts
-the Edge renderer. If SSR must stay, keep the SSR files and explain that a
-supported Node SSR deployment or a Node gateway that cannot be bypassed is
-needed. A custom Node SSR adapter requires separate deployment/routing work;
-the static page-function example is not that adapter. Stop and obtain a rendering
-or deployment decision if the current runtime is incompatible. Do not delete
-`server.ts`, `main.server.ts`, SSR providers or hydration as a workaround.
+<!-- END SSR EXAMPLES -->
 
 ### Static apps on Netlify / Vercel
 
@@ -932,7 +1308,7 @@ server endpoints.
 ## Updating an existing generated guide
 
 After installing the new SDK, rerun `stopnetic-js init --platform <same-platform>`
-(preview with `--dry-run`). An unchanged 0.0.2/0.0.3/0.0.4 generated guide is upgraded
+(preview with `--dry-run`). An unchanged 0.0.2/0.0.3/0.0.4/0.0.5 generated guide is upgraded
 with its setup manifest. Your key, cookie secret and server files are preserved.
 Customized guides or handlers require manual merging; switching platforms also
 requires review. This command does not publish, deploy or contact Stopnetic.

package/dist/setup.js

@@ -39,6 +39,7 @@ const legacyGuideDigests = new Set([
   'b1f149af44f9ceb08fb80c18cb5d4b521620196f536d8ad422ab94d15d1d125d', // 0.0.2
   '55e36295b6aa87ad9558cde29786998483095adeae74e149ff5c7fe78507fad7', // published 0.0.3
   '08f919257d8c85af4e56e842705825832ae2810ed68d5c1dfc8405c8f7be7610', // published 0.0.4
+  '45bd696f196c3d1447a978987a787755b239f75e9e6a3697f4efbb210ce75597', // published 0.0.5
 ]);
 const clientGuide = readFileSync(new URL('./client-guide.md', import.meta.url), 'utf8');
 

package/examples/ssr/angular/app.routes.server.ts

@@ -0,0 +1,5 @@
+import { RenderMode, ServerRoute } from '@angular/ssr';
+export const serverRoutes: ServerRoute[] = [
+  // Demo only: merge with existing hybrid modes rather than replacing them.
+  { path: '**', renderMode: RenderMode.Server },
+];

package/examples/ssr/angular/server.ts

@@ -0,0 +1,12 @@
+// Merge into your existing Node SSR entry; retain host settings and context.
+import { AngularAppEngine, createRequestHandler } from '@angular/ssr';
+import { createStopneticAppHandler } from '@stopnetic/js/server';
+
+const engine = new AngularAppEngine();
+let guarded: ReturnType<typeof createStopneticAppHandler> | undefined;
+async function handle(request: Request): Promise<Response> {
+  guarded ??= createStopneticAppHandler(async checked =>
+    await engine.handle(checked) ?? new Response(null, { status: 404 }));
+  return guarded(request);
+}
+export const reqHandler = createRequestHandler(handle);

package/examples/ssr/astro/middleware.js

@@ -0,0 +1,11 @@
+// src/middleware.js. Keep the existing Node deployment adapter.
+import { defineMiddleware } from 'astro:middleware';
+import { createStopneticAppHandler } from '@stopnetic/js/server';
+
+let guarded;
+export const onRequest = defineMiddleware(async (context, next) => {
+  // Public prerender builds only; protected pages must export prerender=false.
+  if (context.isPrerendered) return next();
+  guarded ??= createStopneticAppHandler((_request, run) => run());
+  return guarded(context.request, () => next());
+});

package/examples/ssr/astro/page.astro

@@ -0,0 +1,4 @@
+---
+// Merge this flag into a protected page, preserving its existing content.
+export const prerender = false;
+---

package/examples/ssr/node/fetch.mjs

@@ -0,0 +1,9 @@
+// Wrap your existing Node Request -> Response renderer; retain all context.
+import { createStopneticAppHandler } from '@stopnetic/js/server';
+export function protectSSR(renderApplication) {
+  let guarded;
+  return (request, ...context) => {
+    guarded ??= createStopneticAppHandler(renderApplication);
+    return guarded(request, ...context);
+  };
+}

package/examples/ssr/node/install.mjs

@@ -0,0 +1,9 @@
+// Call before parsers, static files, APIs and your existing Node SSR renderer.
+import { createStopneticServer } from '@stopnetic/js/server';
+export function installStopneticSSR(app) {
+  let server;
+  app.use((req, res, next) => {
+    server ??= createStopneticServer();
+    return server.access(req, res, () => server.guard(req, res, next));
+  });
+}

package/examples/ssr/nuxt/middleware.mjs

@@ -0,0 +1,10 @@
+// server/middleware/00-stopnetic.mjs. Nuxt 3/4, Nitro 2, H3 1, NODE only.
+// Use server middleware, not app/middleware or defineNuxtRouteMiddleware.
+import { fromNodeMiddleware } from 'h3';
+import { createStopneticServer } from '@stopnetic/js/server';
+
+let server;
+export default fromNodeMiddleware((req, res, next) => {
+  server ??= createStopneticServer();
+  return server.access(req, res, () => server.guard(req, res, next));
+});

package/examples/ssr/react/install.mjs

@@ -0,0 +1,10 @@
+// Existing custom React SSR server: call before assets, APIs and React rendering.
+// Keep renderToPipeableStream/renderToReadableStream and hydration unchanged.
+import { createStopneticServer } from '@stopnetic/js/server';
+export function installStopneticReactSSR(app) {
+  let server;
+  app.use((req, res, next) => {
+    server ??= createStopneticServer();
+    return server.access(req, res, () => server.guard(req, res, next));
+  });
+}

package/examples/ssr/react-router/install.mjs

@@ -0,0 +1,22 @@
+// Call installStopneticReactRouter(app) before parsers, assets and the existing
+// @react-router/express createRequestHandler. Keep that handler/context intact.
+import { createStopneticServer } from '@stopnetic/js/server';
+
+export function installStopneticReactRouter(app) {
+  let server;
+  app.use((req, res, next) => {
+    server ??= createStopneticServer();
+    return server.access(req, res, () => {
+      // React Router 7 single-fetch data URLs must use the page's policy.
+      // The renderer still receives the original request and unread body.
+      const url = new URL(req.originalUrl || req.url, 'https://example.invalid');
+      let checked = req;
+      if (url.pathname.endsWith('.data')) {
+        url.pathname = url.pathname === '/_root.data' ? '/' : url.pathname.slice(0, -5);
+        checked = Object.create(req);
+        checked.originalUrl = url.pathname + url.search;
+      }
+      return server.guard(checked, res, next);
+    });
+  });
+}

package/examples/ssr/solidstart/middleware-v1.js

@@ -0,0 +1,19 @@
+// SolidStart 1: register using defineConfig({ middleware: './src/middleware.js' }).
+// Keep the existing entry-server.tsx renderer. This is NOT SolidStart 2 config.
+import { createMiddleware } from '@solidjs/start/middleware';
+import { createStopneticAppHandler } from '@stopnetic/js/server';
+
+let check;
+export default createMiddleware({
+  onRequest: async event => {
+    check ??= createStopneticAppHandler((_request, state) => {
+      state.allowed = true;
+      return new Response(null, { status: 204 });
+    });
+    const state = { allowed: false };
+    const response = await check(event.request, state);
+    if (!state.allowed) return response;
+    event.response.headers.set('cache-control', 'private, no-store');
+    // undefined continues to SolidStart; preserve its rendering and API handling.
+  },
+});

package/examples/ssr/solidstart/middleware-v2.js

@@ -0,0 +1,25 @@
+// SolidStart 2: register this module using solidStart({ middleware: ... }).
+import { createMiddleware } from '@solidjs/start/middleware';
+import { createStopneticAppHandler } from '@stopnetic/js/server';
+
+let check;
+export default createMiddleware([
+  async (event, next) => {
+    check ??= createStopneticAppHandler((_request, state) => {
+      state.allowed = true;
+      return new Response(null, { status: 204 });
+    });
+    // Per-request state: a verification 204 must NEVER be mistaken for permission.
+    const state = { allowed: false };
+    const response = await check(event.req, state);
+    if (!state.allowed) return response;
+    event.res.headers.set('cache-control', 'private, no-store');
+    const result = await next(); // Preserve H3/SolidStart context and raw results.
+    if (!(result instanceof Response)) return result;
+    const headers = new Headers(result.headers);
+    headers.set('cache-control', 'private, no-store');
+    return new Response(result.body, {
+      status: result.status, statusText: result.statusText, headers,
+    });
+  },
+]);

package/examples/ssr/sveltekit/hooks.server.js

@@ -0,0 +1,16 @@
+import { building } from '$app/environment';
+import { createStopneticAppHandler } from '@stopnetic/js/server';
+
+let guarded;
+// When merging existing hooks, run this first and put them in the continuation.
+export async function handle({ event, resolve }) {
+  // Build-time public prerendering only. Protected routes must have prerender=false.
+  if (building) return resolve(event);
+  guarded ??= createStopneticAppHandler((_request, run) => run());
+  // SvelteKit exposes the canonical page URL on data requests. Check that page
+  // rather than allowing an unmatched /members/__data.json alias through.
+  const checked = event.isDataRequest
+    ? new Request(event.url, { method: event.request.method, headers: event.request.headers })
+    : event.request;
+  return guarded(checked, () => resolve(event));
+}

package/examples/ssr/sveltekit/page.server.js

@@ -0,0 +1,3 @@
+// Merge into the PROTECTED route's +page.server.js, retaining loads/actions.
+export const prerender = false;
+export const ssr = true;

package/examples/ssr/vue/install.mjs

@@ -0,0 +1,10 @@
+// Existing custom Vue SSR server: call before assets, APIs and Vue rendering.
+// Keep createSSRApp/renderToString and client hydration unchanged.
+import { createStopneticServer } from '@stopnetic/js/server';
+export function installStopneticVueSSR(app) {
+  let server;
+  app.use((req, res, next) => {
+    server ??= createStopneticServer();
+    return server.access(req, res, () => server.guard(req, res, next));
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stopnetic/js",
-  "version": "0.0.5-pilot",
+  "version": "0.0.6-pilot",
   "description": "Server-side Stopnetic guard for JavaScript websites, Node.js and Express-compatible servers.",
   "type": "module",
   "license": "MIT",
@@ -20,7 +20,8 @@
   "files": [
     "dist",
     "bin",
-    "examples/frontend"
+    "examples/frontend",
+    "examples/ssr"
   ],
   "bin": { "stopnetic-js": "./bin/stopnetic-js.js" },
   "exports": {