@stopnetic/js 0.0.2-pilot → 0.0.4-pilot

package/dist/client-guide.md

@@ -0,0 +1,828 @@
+# Stopnetic setup for JavaScript applications
+
+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.
+
+Jump to your implementation: [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
+layout, navigation and protected API example, not just the startup function.
+
+The generated control endpoint is only part of installation. It does not
+automatically intercept pages, edit your router or protect existing APIs.
+
+## 1. Choose the actual rendering and server runtime
+
+| Application | Where the shared guard belongs |
+| --- | --- |
+| Node/Express SSR or static-file server | Before body parsers, static files, API handlers and rendering |
+| Node server with a Fetch `Request` → `Response` handler | Wrap the complete application handler before it renders or returns API data |
+| Static Angular, React, Vue, Svelte, Solid or plain HTML | A Node hosting function/middleware before HTML, plus the shared browser check below |
+| Angular SSR, Nuxt, SvelteKit, Astro, SolidStart, React Router server mode | The deployed Node request entry, before the framework renderer; preserve framework context |
+| Next.js | Use `@stopnetic/next` and its Next.js installation guide |
+| Edge/Deno/Cloudflare Workers, PHP, Python, Ruby, C# or Java | This Node SDK cannot be imported there; use a Node gateway or an adapter for that runtime |
+
+Node.js 22 or newer is required. SSR support alone does not establish runtime
+compatibility. A Fetch API on an Edge runtime is not a Node server.
+Prerendering runs at build time: it is not a request-time access check. Do not
+publish protected prerendered pages or private data to a public static directory.
+
+## 2. Save the six server environment settings
+
+Copy actual values from Stopnetic Integration into your hosting SERVER
+environment. Use `https://www.example.com` only as an example; replace it with
+your website's canonical origin.
+
+```dotenv
+STOPNETIC_WEBSITE_ORIGIN=https://www.example.com
+STOPNETIC_SITE_ID=your_site_id
+STOPNETIC_API_URL=https://your-stopnetic-service/api/integration/decision
+STOPNETIC_API_TOKEN=your_private_installation_key
+STOPNETIC_DECISION_PUBLIC_KEY=your_complete_public_PEM
+STOPNETIC_COOKIE_SECRET=your_separate_random_cookie_secret
+```
+
+The installer creates a private cookie secret in `.env.local` when missing.
+Reuse it across deployments. Do not commit `.env.local`. Copy complete PEM
+header/body/footer with real newlines or literal `\n`; quote multiline values
+in local env files. Hosting value fields do not need surrounding quotes.
+Never put private settings in frontend environment files or prefix them with
+`VITE_`, `REACT_APP_` or `NEXT_PUBLIC_`. Angular's `environment.ts` is browser
+configuration, not a private server environment.
+
+## 3. Protect the server before rendering
+
+### Node/Express: every frontend uses the same mount
+
+```js
+import { installStopnetic } from './stopnetic.server.mjs';
+installStopnetic(app);
+// Existing body parsers, static files, APIs and framework renderer follow.
+```
+
+Generate that helper with `stopnetic-js init --platform node`. Only expose the
+guarded server. Keep the control endpoints `/api/stopnetic/access` and
+`/api/stopnetic/verify` reachable before SPA fallbacks. Preserve the canonical
+Host at your proxy. This works without a React dependency or browser boundary.
+
+### Node Fetch application: one wrapper for pages and APIs
+
+In SDK 0.0.3-pilot or newer:
+
+```js
+import { createStopneticAppHandler } from '@stopnetic/js/server';
+
+let protectedApp;
+export async function handleRequest(request, context) {
+  protectedApp ??= createStopneticAppHandler(async (checked, frameworkContext) => {
+    // Your existing Node framework handler. Return a Response.
+    return renderApplication(checked, frameworkContext);
+  });
+  return protectedApp(request, context);
+}
+```
+
+Lazy initialization reads environment settings at runtime, not during a
+prerender build. Control requests are handled by Stopnetic. Other requests are
+checked before the application handler runs; denied responses do not render
+the site's navigation or private API data. Context and unread request bodies
+are preserved. Continue enforcing your application's own user/data permissions.
+
+For a framework hook, keep its existing request/context conventions and call
+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.
+
+### Angular SSR on Node
+
+For a Fetch-style Angular SSR entry in `src/server.ts`:
+
+```ts
+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);
+```
+
+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`:
+
+```ts
+import { RenderMode, ServerRoute } from '@angular/ssr';
+export const serverRoutes: ServerRoute[] = [
+  // All routes are rendered on incoming requests in this example.
+  { path: '**', renderMode: RenderMode.Server },
+];
+```
+
+Netlify's automatic Angular SSR adapter currently uses Edge Functions. Do not
+import this Node SDK into that Edge entry, and do not assume a Netlify Node
+function runs before the Edge renderer. Use a Node SSR deployment, a Node
+gateway that cannot be bypassed, or a static Angular build with Node page
+handling. Switching to static rendering changes SSR behavior; choose deliberately.
+
+### Static apps on Netlify / Vercel
+
+The generated Netlify control file serves `/api/stopnetic/access` and
+`/api/stopnetic/verify`; Vercel uses `api/stopnetic/[operation].mjs`. They do not
+guard the original page request by themselves. Add a Node page function or
+Node routing middleware before serving HTML if you need real page HTTP 404s.
+The full hosting guide is at your Stopnetic dashboard's `/docs#javascript`.
+
+Use your actual build output. Vite often uses `dist`; Angular commonly uses
+`dist/<project>/browser`. Angular scripts/styles may be at that directory's
+root rather than `/assets`. Bundle the correct HTML and assets, preserve their
+MIME types, and do not use the Vite-only file paths unchanged for Angular.
+Reject direct entry-HTML and function aliases that would bypass protected paths.
+
+## 4. Browser startup: the same code for every frontend
+
+For a browser-only/static app, move the existing startup code from `src/main.ts`
+or `src/main.js` into `src/bootstrap.ts` or `src/bootstrap.js`. Keep its original
+framework imports and bootstrap code. Replace the browser entry with:
+
+```js
+import { checkAccess } from '@stopnetic/js/browser';
+
+async function start() {
+  try {
+    const result = await checkAccess(location.pathname + location.search);
+    if (result.allowed) {
+      await import('./bootstrap'); // Your existing app startup, unchanged.
+    } else if (result.reason === 'verification_required' && result.verificationUrl) {
+      location.replace(result.verificationUrl);
+    } else {
+      document.body.replaceChildren(document.createTextNode(
+        result.reason === 'blocked' ? 'Not found.' : 'Access unavailable.'));
+    }
+  } catch {
+    document.body.replaceChildren(document.createTextNode('Access unavailable.'));
+  }
+}
+void start();
+```
+
+This is browser code, not a server hook. The startup file can use any framework:
+
+| Frontend | Existing startup retained in `bootstrap` |
+| --- | --- |
+| Angular | `bootstrapApplication(App, appConfig)` or your existing NgModule bootstrap |
+| React | `createRoot(...).render(...)` |
+| Vue | `createApp(...).use(router).mount(...)` |
+| Svelte | Your existing `mount(...)` or older constructor |
+| Solid | Your existing `render(...)` |
+| Plain JavaScript | Your existing DOM rendering code |
+
+Use ordinary `<a href>` document links for guarded navigation: each navigation
+then reaches the server before a new page is shown. Client router navigation
+does not rerun the startup file. If keeping SPA navigation, call `checkAccess`
+in that router's before-navigation guard for every target and handle denial,
+verification redirects, outages and stale/cancelled requests. A UI check cannot
+set the original HTTP status or make public bundles private.
+
+<!-- BEGIN FRONTEND EXAMPLES -->
+
+### Choose your frontend implementation
+
+The package includes copyable source files in `examples/frontend`. The same
+examples appear below and in the dashboard frontend selector. Choose the
+example for your app; the shared startup above is an alternative. These are
+complete small layouts with sample routes. Merge the guard into your own
+layout and replace the sample pages/paths with your actual pages. Keep all
+navigation, routes and footer inside the gate. The server setup remains required.
+
+These router/layout examples run in the browser. Framework SSR request
+handlers remain in section 3; keep browser checks out of server rendering.
+
+Copy the selected folder under `src/<frontend>/` and the shared data helper
+to `src/load-private-data.js` (plus its `.d.ts` file for TypeScript). This keeps
+the relative imports below valid. Point your browser entry at the example
+`main` file, or import that file from your existing entry when trying the demo.
+React/Vue/Svelte/Solid/plain JS entries expect `<div id="app"></div>`; Angular
+uses `<app-root></app-root>`. Use your own mount target when adapting the code.
+Do not mount your old app outside the gate or mount two apps at once.
+
+- React Router
+- Angular Router
+- Vue Router
+- Svelte navigation
+- Solid Router
+- Plain JavaScript navigation
+
+Shared browser API helper: `src/load-private-data.js`. `/api/private` must
+be guarded on its own server. Angular demonstrates HttpClient instead.
+
+
+```js
+// Browser example. The /api/private SERVER handler must also be guarded.
+export async function loadPrivateData(signal) {
+  const response = await fetch('/api/private', {
+    credentials: 'same-origin', cache: 'no-store', signal,
+    headers: { Accept: 'application/json' },
+  });
+  if (!response.ok) throw new Error(`Request failed (HTTP ${response.status}).`);
+  return response.json();
+}
+```
+
+TypeScript declaration: `src/load-private-data.d.ts`.
+
+
+```ts
+export function loadPrivateData(signal?: AbortSignal): Promise<unknown>;
+```
+
+### React Router
+
+Use BrowserRouter and StopneticBoundary around the full header, routes and footer. Client Link navigation triggers another access check. React Router 6+ style; adapt your existing routes rather than replacing them. Add react-router-dom if your app does not have it.
+
+#### src/react/App.tsx
+
+
+```tsx
+import { useEffect, useState, type ReactNode } from 'react';
+import { BrowserRouter, Link, Route, Routes, useLocation } from 'react-router-dom';
+import { StopneticBoundary } from '@stopnetic/js/react';
+import { loadPrivateData } from '../load-private-data.js';
+
+function RouteGuard({ children }: { children: ReactNode }) {
+  const location = useLocation();
+  return <StopneticBoundary path={location.pathname + location.search}
+    pending={<p>Checking access...</p>}
+    blocked={<p>Access unavailable.</p>}>
+    {children}
+  </StopneticBoundary>;
+}
+
+function Members() {
+  const [data, setData] = useState('Loading data...');
+  useEffect(() => {
+    const controller = new AbortController();
+    loadPrivateData(controller.signal)
+      .then(value => { if (!controller.signal.aborted) setData(JSON.stringify(value) ?? 'No data.'); })
+      .catch(() => { if (!controller.signal.aborted) setData('API access unavailable.'); });
+    return () => controller.abort();
+  }, []);
+  return <main><h1>Members</h1><p>{data}</p></main>;
+}
+
+function Layout() {
+  return <>
+    <header><nav>
+      <Link to="/">Home</Link>{' '}<Link to="/members">Members</Link>{' '}
+      <Link to="/slow">Slow</Link>{' '}<Link to="/blocked">Blocked</Link>{' '}
+      <Link to="/offline">Offline</Link>
+    </nav></header>
+    <Routes>
+      <Route caseSensitive path="/" element={<main><h1>Home</h1></main>}/>
+      <Route caseSensitive path="/members" element={<Members/>}/>
+      <Route caseSensitive path="/slow" element={<main><h1>Slow</h1></main>}/>
+      <Route caseSensitive path="/blocked" element={<main><h1>Blocked</h1></main>}/>
+      <Route caseSensitive path="/offline" element={<main><h1>Offline</h1></main>}/>
+      <Route path="*" element={<main><h1>Not found</h1></main>}/>
+    </Routes>
+    <footer>Example site</footer>
+  </>;
+}
+
+export default function App() {
+  return <BrowserRouter><RouteGuard><Layout/></RouteGuard></BrowserRouter>;
+}
+```
+
+#### src/react/main.tsx
+
+
+```tsx
+import { createRoot } from 'react-dom/client';
+import App from './App';
+createRoot(document.getElementById('app')!).render(<App/>);
+```
+
+### Angular Router
+
+The service records checking/allowed/denied state. Apply the route guard to every page and gate the full layout. Members uses HttpClient after route access succeeds. Merge providers into your existing appConfig, keeping SSR/hydration settings. This standalone example uses modern Angular syntax.
+
+#### src/angular/app/app.config.ts
+
+
+```ts
+import { ApplicationConfig } from '@angular/core';
+import { provideHttpClient } from '@angular/common/http';
+import { provideRouter } from '@angular/router';
+import { routes } from './app.routes';
+export const appConfig: ApplicationConfig = {
+  providers: [provideRouter(routes), provideHttpClient()],
+};
+// Merge these providers into your existing appConfig; retain its other settings.
+```
+
+#### src/angular/app/app.routes.ts
+
+
+```ts
+import { Component } from '@angular/core';
+import { Routes } from '@angular/router';
+import { MembersPage } from './members.page';
+import { stopneticRouteGuard } from './stopnetic-access.service';
+
+@Component({ template: '<main><h1>Home</h1></main>' })
+class HomePage {}
+@Component({ template: '<main><h1>Slow</h1></main>' })
+class OtherPage {}
+
+const pages: Routes = [
+  { path: '', pathMatch: 'full', component: HomePage },
+  { path: 'members', component: MembersPage },
+  { path: 'slow', component: OtherPage },
+  { path: 'blocked', component: OtherPage },
+  { path: 'offline', component: OtherPage },
+];
+export const routes: Routes = pages.map(route => ({
+  ...route, canActivate: [stopneticRouteGuard], runGuardsAndResolvers: 'always' as const,
+}));
+```
+
+#### src/angular/app/app.ts
+
+
+```ts
+import { Component, inject } from '@angular/core';
+import { RouterLink, RouterOutlet } from '@angular/router';
+import { StopneticAccess } from './stopnetic-access.service';
+
+@Component({
+  selector: 'app-root', imports: [RouterLink, RouterOutlet],
+  template: `
+    @if (access.state() === 'allowed') {
+      <header><nav>
+        <a routerLink="/">Home</a> <a routerLink="/members">Members</a>
+        <a routerLink="/slow">Slow</a> <a routerLink="/blocked">Blocked</a>
+        <a routerLink="/offline">Offline</a>
+      </nav></header>
+      <router-outlet/>
+      <footer>Example site</footer>
+    } @else if (access.state() === 'checking') {
+      <p role="status">Checking access...</p>
+    } @else {
+      <p role="alert">Access unavailable.</p>
+    }
+  `,
+})
+export class App { readonly access = inject(StopneticAccess); }
+```
+
+#### src/angular/app/members.page.ts
+
+
+```ts
+import { isPlatformBrowser } from '@angular/common';
+import { Component, DestroyRef, inject, OnInit, PLATFORM_ID, signal } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+
+@Component({ template: '<main><h1>Members</h1><p>{{ data() }}</p></main>' })
+export class MembersPage implements OnInit {
+  readonly data = signal('Loading data...');
+  private readonly http = inject(HttpClient);
+  private readonly destroyRef = inject(DestroyRef);
+  private readonly platform = inject(PLATFORM_ID);
+  ngOnInit() {
+    // This example loads data in the browser. SSR fetches need request cookies
+    // forwarded explicitly, plus server authorization; do not bypass the guard.
+    if (!isPlatformBrowser(this.platform)) return;
+    this.http.get('/api/private', { withCredentials: true })
+      .pipe(takeUntilDestroyed(this.destroyRef))
+      .subscribe({ next: value => this.data.set(JSON.stringify(value)),
+        error: () => this.data.set('API access unavailable.') });
+  }
+}
+```
+
+#### src/angular/app/stopnetic-access.service.ts
+
+
+```ts
+import { isPlatformBrowser } from '@angular/common';
+import { inject, Injectable, PLATFORM_ID, signal } from '@angular/core';
+import { CanActivateFn } from '@angular/router';
+import { checkAccess } from '@stopnetic/js/browser';
+
+@Injectable({ providedIn: 'root' })
+export class StopneticAccess {
+  readonly state = signal<'checking' | 'allowed' | 'denied'>('checking');
+  private readonly platform = inject(PLATFORM_ID);
+  private current?: AbortController;
+  async check(path: string): Promise<boolean> {
+    // Node SSR must be authorized by the SERVER guard before Angular renders.
+    if (!isPlatformBrowser(this.platform)) { this.state.set('allowed'); return true; }
+    this.current?.abort();
+    const controller = new AbortController(); this.current = controller;
+    this.state.set('checking');
+    try {
+      const result = await checkAccess(path.split('#')[0], { signal: controller.signal });
+      if (controller.signal.aborted) return false;
+      if (result.allowed) { this.state.set('allowed'); return true; }
+      if (result.reason === 'verification_required' && result.verificationUrl) location.assign(result.verificationUrl);
+    } catch { if (controller.signal.aborted) return false; }
+    this.state.set('denied'); return false;
+  }
+}
+export const stopneticRouteGuard: CanActivateFn = (_route, state) =>
+  inject(StopneticAccess).check(state.url);
+```
+
+#### src/angular/main.ts
+
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { App } from './app/app';
+import { appConfig } from './app/app.config';
+bootstrapApplication(App, appConfig).catch(error => console.error(error));
+```
+
+### Vue Router
+
+Vue 3 and Vue Router 4: beforeEach checks the target and cancels stale checks. App.vue hides the entire layout while checking or denied. afterEach shows it only after a successful navigation. Add vue-router if needed.
+
+#### src/vue/App.vue
+
+
+```vue
+<script setup>
+import { RouterLink, RouterView } from 'vue-router';
+import { accessState } from './router.js';
+</script>
+
+<template>
+  <template v-if="accessState === 'allowed'">
+    <header><nav>
+      <RouterLink to="/">Home</RouterLink> <RouterLink to="/members">Members</RouterLink>
+      <RouterLink to="/slow">Slow</RouterLink> <RouterLink to="/blocked">Blocked</RouterLink>
+      <RouterLink to="/offline">Offline</RouterLink>
+    </nav></header>
+    <RouterView/>
+    <footer>Example site</footer>
+  </template>
+  <p v-else-if="accessState === 'checking'" role="status">Checking access...</p>
+  <p v-else role="alert">Access unavailable.</p>
+</template>
+```
+
+#### src/vue/main.js
+
+
+```js
+import { createApp } from 'vue';
+import App from './App.vue';
+import { router } from './router.js';
+createApp(App).use(router).mount('#app');
+```
+
+#### src/vue/Members.vue
+
+
+```vue
+<script setup>
+import { onMounted, onUnmounted, ref } from 'vue';
+import { loadPrivateData } from '../load-private-data.js';
+const data = ref('Loading data...');
+const controller = new AbortController();
+onMounted(() => {
+  loadPrivateData(controller.signal)
+    .then(value => { if (!controller.signal.aborted) data.value = JSON.stringify(value); })
+    .catch(() => { if (!controller.signal.aborted) data.value = 'API access unavailable.'; });
+});
+onUnmounted(() => controller.abort());
+</script>
+
+<template><main><h1>Members</h1><p>{{ data }}</p></main></template>
+```
+
+#### src/vue/router.js
+
+
+```js
+import { h, ref } from 'vue';
+import { createRouter, createWebHistory } from 'vue-router';
+import { checkAccess } from '@stopnetic/js/browser';
+import Members from './Members.vue';
+
+export const accessState = ref('checking');
+const page = title => ({ render: () => h('main', h('h1', title)) });
+export const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    { path: '/', component: page('Home') },
+    { path: '/members', component: Members },
+    { path: '/slow', component: page('Slow') },
+    { path: '/blocked', component: page('Blocked') },
+    { path: '/offline', component: page('Offline') },
+  ],
+});
+
+let current;
+let approvedPath = '';
+router.beforeEach(async to => {
+  current?.abort();
+  const controller = new AbortController();
+  current = controller;
+  approvedPath = '';
+  accessState.value = 'checking';
+  try {
+    const result = await checkAccess(to.fullPath.split('#')[0], { signal: controller.signal });
+    if (controller.signal.aborted) return false;
+    if (result.allowed) { approvedPath = to.fullPath; return true; }
+    if (result.reason === 'verification_required' && result.verificationUrl) {
+      location.assign(result.verificationUrl);
+    }
+    accessState.value = 'denied';
+  } catch { if (!controller.signal.aborted) accessState.value = 'denied'; }
+  return false;
+});
+router.afterEach((to, _from, failure) => {
+  if (!failure && approvedPath === to.fullPath) accessState.value = 'allowed';
+});
+```
+
+### Svelte navigation
+
+Svelte 5 example with onMount, History API navigation, popstate and abort cleanup. The full layout stays hidden until access succeeds. It does not require a third-party router. For SvelteKit SSR, retain server-side enforcement and integrate its own navigation lifecycle; this is a standalone Svelte app.
+
+#### src/svelte/App.svelte
+
+
+```svelte
+<script>
+  import { onMount } from 'svelte';
+  import { checkAccess } from '@stopnetic/js/browser';
+  import { loadPrivateData } from '../load-private-data.js';
+
+  let path = '';
+  let state = 'checking';
+  let data = '';
+  let current;
+  async function showPage() {
+    current?.abort();
+    const controller = new AbortController();
+    current = controller;
+    path = location.pathname;
+    state = 'checking'; data = '';
+    try {
+      const result = await checkAccess(path + location.search, { signal: controller.signal });
+      if (controller.signal.aborted) return;
+      if (!result.allowed) {
+        if (result.reason === 'verification_required' && result.verificationUrl) location.assign(result.verificationUrl);
+        state = 'denied'; return;
+      }
+      state = 'allowed';
+      if (path === '/members') {
+        data = 'Loading data...';
+        try {
+          const value = await loadPrivateData(controller.signal);
+          if (!controller.signal.aborted) data = JSON.stringify(value);
+        } catch { if (!controller.signal.aborted) data = 'API access unavailable.'; }
+      }
+    } catch { if (!controller.signal.aborted) state = 'denied'; }
+  }
+  function navigate(event) {
+    if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    event.preventDefault();
+    history.pushState(null, '', event.currentTarget.href);
+    void showPage();
+  }
+  onMount(() => {
+    void showPage();
+    addEventListener('popstate', showPage);
+    return () => { current?.abort(); removeEventListener('popstate', showPage); };
+  });
+</script>
+
+{#if state === 'allowed'}
+  <header><nav>
+    <a href="/" onclick={navigate}>Home</a> <a href="/members" onclick={navigate}>Members</a>
+    <a href="/slow" onclick={navigate}>Slow</a> <a href="/blocked" onclick={navigate}>Blocked</a>
+    <a href="/offline" onclick={navigate}>Offline</a>
+  </nav></header>
+  <main><h1>{path === '/members' ? 'Members' : path === '/' ? 'Home' : path === '/slow' ? 'Slow' : 'Not found'}</h1><p>{data}</p></main>
+  <footer>Example site</footer>
+{:else if state === 'checking'}
+  <p role="status">Checking access...</p>
+{:else}
+  <p role="alert">Access unavailable.</p>
+{/if}
+```
+
+#### src/svelte/main.js
+
+
+```js
+// Svelte 5 entry. Svelte 4 apps retain their existing `new App(...)` entry.
+import { mount } from 'svelte';
+import App from './App.svelte';
+mount(App, { target: document.getElementById('app') });
+```
+
+### Solid Router
+
+Solid Router root layout uses useLocation and reactive checks. The Show boundary creates the full layout only for the checked path, and cleanup aborts stale checks. Add @solidjs/router if needed. This browser example does not replace SolidStart server authorization.
+
+#### src/solid/App.tsx
+
+
+```tsx
+import { createEffect, createSignal, onCleanup, Show, type ParentComponent } from 'solid-js';
+import { A, Route, Router, useLocation } from '@solidjs/router';
+import { checkAccess } from '@stopnetic/js/browser';
+import { loadPrivateData } from '../load-private-data.js';
+
+const GuardedLayout: ParentComponent = props => {
+  const location = useLocation();
+  const path = () => location.pathname + location.search;
+  const [result, setResult] = createSignal({ path: '', allowed: false, pending: true });
+  createEffect(() => {
+    const target = path();
+    const controller = new AbortController();
+    setResult({ path: target, allowed: false, pending: true });
+    checkAccess(target, { signal: controller.signal }).then(value => {
+      if (controller.signal.aborted) return;
+      if (!value.allowed && value.reason === 'verification_required' && value.verificationUrl) locationRedirect(value.verificationUrl);
+      setResult({ path: target, allowed: value.allowed, pending: false });
+    }).catch(() => {
+      if (!controller.signal.aborted) setResult({ path: target, allowed: false, pending: false });
+    });
+    onCleanup(() => controller.abort());
+  });
+  return <Show when={result().allowed && result().path === path() ? result() : undefined}
+    fallback={<Show when={result().pending || result().path !== path()}
+      fallback={<p role="alert">Access unavailable.</p>}><p role="status">Checking access...</p></Show>}>
+    {_checked => <>
+      <header><nav><A href="/">Home</A>{' '}<A href="/members">Members</A>{' '}
+        <A href="/slow">Slow</A>{' '}<A href="/blocked">Blocked</A>{' '}<A href="/offline">Offline</A>
+      </nav></header>
+      {props.children}
+      <footer>Example site</footer>
+    </>}
+  </Show>;
+};
+const locationRedirect = (url: string) => window.location.assign(url);
+
+function Members() {
+  const [data, setData] = createSignal('Loading data...');
+  const controller = new AbortController();
+  loadPrivateData(controller.signal)
+    .then(value => { if (!controller.signal.aborted) setData(JSON.stringify(value) ?? 'No data.'); })
+    .catch(() => { if (!controller.signal.aborted) setData('API access unavailable.'); });
+  onCleanup(() => controller.abort());
+  return <main><h1>Members</h1><p>{data()}</p></main>;
+}
+export default function App() {
+  return <Router root={GuardedLayout}>
+    <Route path="/" component={() => <main><h1>Home</h1></main>}/>
+    <Route path="/members" component={Members}/>
+    <Route path="/slow" component={() => <main><h1>Slow</h1></main>}/>
+    <Route path="/blocked" component={() => <main><h1>Blocked</h1></main>}/>
+    <Route path="/offline" component={() => <main><h1>Offline</h1></main>}/>
+  </Router>;
+}
+```
+
+#### src/solid/main.tsx
+
+
+```tsx
+import { render } from 'solid-js/web';
+import App from './App';
+render(() => <App/>, document.getElementById('app')!);
+```
+
+### Plain JavaScript navigation
+
+Create the full layout only after checkAccess allows the target. Clicks and browser back/forward rerun the check. Abort old checks and data loads. Bundle this module with your browser build; native browsers need bundled imports or an import map.
+
+#### src/vanilla/main.js
+
+
+```js
+import { checkAccess } from '@stopnetic/js/browser';
+import { loadPrivateData } from '../load-private-data.js';
+const root = document.getElementById('app');
+let current;
+async function showPage() {
+  current?.abort();
+  const controller = new AbortController(); current = controller;
+  root.replaceChildren(document.createTextNode('Checking access...'));
+  try {
+    const path = location.pathname;
+    const result = await checkAccess(path + location.search, { signal: controller.signal });
+    if (controller.signal.aborted) return;
+    if (!result.allowed) {
+      if (result.reason === 'verification_required' && result.verificationUrl) location.assign(result.verificationUrl);
+      const alert = document.createElement('p'); alert.setAttribute('role', 'alert');
+      alert.textContent = 'Access unavailable.'; root.replaceChildren(alert); return;
+    }
+    const header = document.createElement('header');
+    const nav = document.createElement('nav'); header.append(nav);
+    for (const [url, name] of [['/', 'Home'], ['/members', 'Members'], ['/slow', 'Slow'], ['/blocked', 'Blocked'], ['/offline', 'Offline']]) {
+      const link = document.createElement('a'); link.href = url; link.textContent = name;
+      link.addEventListener('click', event => {
+        if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+        event.preventDefault(); history.pushState(null, '', url); void showPage();
+      });
+      nav.append(link, document.createTextNode(' '));
+    }
+    const main = document.createElement('main'); const heading = document.createElement('h1');
+    heading.textContent = path === '/members' ? 'Members' : path === '/' ? 'Home' : path === '/slow' ? 'Slow' : 'Not found';
+    const data = document.createElement('p'); main.append(heading, data);
+    const footer = document.createElement('footer'); footer.textContent = 'Example site';
+    root.replaceChildren(header, main, footer);
+    if (path === '/members') {
+      data.textContent = 'Loading data...';
+      try {
+        const value = await loadPrivateData(controller.signal);
+        if (!controller.signal.aborted) data.textContent = JSON.stringify(value);
+      } catch { if (!controller.signal.aborted) data.textContent = 'API access unavailable.'; }
+    }
+  } catch {
+    if (!controller.signal.aborted) root.replaceChildren(document.createTextNode('Access unavailable.'));
+  }
+}
+addEventListener('popstate', showPage);
+addEventListener('pagehide', () => current?.abort());
+void showPage();
+```
+
+<!-- END FRONTEND EXAMPLES -->
+
+## 5. Protect APIs independently
+
+If the full application wrapper is in front of an API, it checks that API too.
+Separate Netlify/Vercel API functions need their own wrapper:
+
+```js
+import { withStopnetic } from '@stopnetic/js/server';
+const handler = withStopnetic(async (request, context) => {
+  // Also enforce your application's login/data permissions.
+  return Response.json({ example: true });
+});
+// Netlify: export default handler;
+// export const config = { path: '/api/private', preferStatic: false };
+// Vercel: export default { fetch: handler };
+```
+
+Use the public custom `/api/private` path in all clients and Policies, not
+Netlify's default `/.netlify/functions/` alias. Fetch same-origin data with
+`credentials: 'same-origin'`. API requests cannot run a verification page;
+verify on an HTML page first. An API on another origin needs its own server
+protection and session, or a guarded same-origin server proxy. CORS alone does
+not authorize data, and the current SDK does not share sessions across hosts.
+
+## 6. Rules, deployment and testing
+
+Save the actual page as Page / Automatic browser flow and its APIs as API /
+Require verified session in Policies. First matching rule wins. Unmatched paths
+are public in the generated site's whole-site mode. Public and block rules still
+require a valid signed policy response. Verification can be completed by capable
+automated browsers; retain your own authentication and authorization.
+
+Run `stopnetic-js check`, build and deploy. Configure server env in each hosted
+context and redeploy after changing it. For local Netlify/Vercel functions use
+the full local server, not just `ng serve` or Vite. For Node use
+`node --env-file=.env.local your-server.mjs` or your server environment loader.
+
+Test raw document requests, verified browser requests, direct private API calls,
+denial and service failure. Check status/body, session cookies, JS/CSS MIME types,
+client navigation, entry HTML, aliases, prerender outputs and caches. A denied
+request must not execute the renderer or data handler. The offline CLI check
+validates configuration and generated files, not deployed coverage.
+
+Ordinary policy changes apply on subsequent guarded requests without reinstalling
+or redeploying. Already loaded content is not recalled. Public HTML/JS/assets and
+content bundled into frontend code remain public; keep private data in guarded
+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 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.
+
+References: https://angular.dev/guide/ssr,
+https://angular.dev/guide/routing/route-guards,
+https://docs.netlify.com/build/frameworks/framework-setup-guides/angular/.