@stopnetic/js 0.0.3-pilot → 0.0.5-pilot

package/dist/client-guide.md

@@ -4,11 +4,70 @@ Angular, React, Vue, Svelte, Solid and plain JavaScript use the same server guar
 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.
 
+## Integration contract — read before editing an existing app
+
+1. Inspect the existing server entry, rendering modes, hosting adapter and router.
+   Preserve SSR, hydration, public pages, routes and application features.
+   Installing Stopnetic is not authorization to convert SSR to CSR, delete server
+   files, replace the application's router or copy the demo over an existing app.
+2. Choose ONE of the two rendering paths below. Keep the app's current rendering
+   by default. A hosting/runtime incompatibility must be explained to the owner;
+   do not resolve it by silently removing SSR or changing hosting.
+3. Install the guard before the existing server renders or serves HTML. Keep the
+   existing browser bootstrap unchanged for the default document-navigation mode.
+   Do not add a global `Checking access...` screen or a browser startup gate.
+4. Save protected paths in Stopnetic Policies. Do not add the demo paths, protect
+   every page, copy dashboard rules into a frontend path list, or change defaults
+   without the owner's instruction. Guards evaluate requests; they do not make
+   every evaluated request require verification.
+5. Use normal document navigation for the simplest server-enforced integration.
+   If retaining client-side SPA navigation is required, use the OPTIONAL router
+   examples and explain their asynchronous checks before adding them.
+6. Independently guard private API handlers. Validate public, protected and denied
+   pages plus SSR output before declaring integration complete.
+
+## What visitors should see
+
+For example, suppose only `/members` is Page / Automatic browser flow:
+
+| Request | Normal behavior |
+| --- | --- |
+| `/`, `/about`, `/contact` with no matching rule | Public page; normal layout, no Stopnetic checking screen or verification |
+| `/members` without a valid session | Server verification flow before returning the page |
+| `/members` with a valid session | Normal page content |
+| A Page / Block route | Empty HTTP 404 before any site layout renders |
+| A protected API without a valid session | HTTP 404; no JSON data and no browser challenge |
+
+Generated site mode leaves unmatched paths public; explicit broader rules can
+change that. Public requests still need a valid signed policy response. A service
+failure returns 503 rather than bypassing policy. Rules belong in the dashboard;
+the browser cannot know whether a target is public until the server checks it.
+
 ## 1. Choose the actual rendering and server runtime
 
+**Option A — preserve SSR.** Keep the existing renderer, server entry and
+hydration. Add the Node guard before the renderer (section 3). Use server
+document navigation (section 4). Public pages render normally; protected pages
+render only after the dashboard decision permits them.
+
+**Option B — retain a static/CSR frontend.** Keep the existing browser bootstrap
+and build. Add a Node hosting page guard before HTML (section 3), then use server
+document navigation (section 4). A Node function serving built `index.html` is
+static page handling, not SSR. Choose this option for an existing static app or
+only after an explicit decision to convert rendering.
+
+Neither option requires a global browser boundary. Optional SPA navigation is
+a separate choice, not a third rendering mode.
+
 | Application | Where the shared guard belongs |
 | --- | --- |
 | Node/Express SSR or static-file server | Before body parsers, static files, API handlers and rendering |
@@ -122,11 +181,21 @@ export const serverRoutes: ServerRoute[] = [
 ];
 ```
 
-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.
+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.
+
+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.
 
 ### Static apps on Netlify / Vercel
 
@@ -142,7 +211,55 @@ 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
+## 4. Navigation — server enforcement by default
+
+For BOTH rendering options, leave the existing browser entry and app layout
+alone. Use document links for page navigation so every target reaches the
+guarded server before rendering. No global `checkAccess`, `StopneticBoundary`,
+startup import gate, root access service or loading message is required.
+
+| Frontend | Document navigation |
+| --- | --- |
+| Angular | `<a href="/members">Members</a>` instead of `routerLink` for this navigation |
+| React | `<a href="/members">Members</a>` instead of router `<Link>` |
+| Vue | `<a href="/members">Members</a>` instead of `<RouterLink>` |
+| Svelte / SvelteKit | `<a href="/members" data-sveltekit-reload>Members</a>`; disable any custom interception |
+| Solid | `<a href="/members" target="_self">Members</a>` instead of router `<A>` |
+| Plain JavaScript | `<a href="/members">Members</a>`; do not intercept it with `pushState` |
+
+Replace programmatic SPA transitions with `location.assign('/members')` when
+using this mode. Turn off router prefetch/preload of protected page data that
+would bypass the guarded document request. Existing routers may still resolve
+the current URL after loading. Normal pages keep their usual loading behavior;
+Stopnetic's verification HTML is sent only when the server decision requires it.
+
+For SSR, hydrate the HTML already authorized by the server. Do not replace it
+with a browser-only loading screen or run a redundant startup check. Private API
+requests remain independently checked by their server handler.
+
+### Optional SPA navigation — explicit asynchronous tradeoff
+
+Retain SPA navigation only when needed. SPA transitions do not make a new
+document request, so check each target in the router before showing its content.
+The current browser API returns access after a server request; it does not
+provide a synchronous dashboard route manifest. Public transitions also need
+that check to discover the current policy. A brief empty pending state is
+possible; it is not a challenge and is not advertised as instant public rendering.
+Use document navigation above if this delay is unacceptable. Do not bypass
+checks with a hardcoded public/protected list, cached `allowed` flag, or client
+user-agent detection. Keep full target content hidden until the check succeeds.
+
+The six optional demos below intentionally check their sample router targets.
+They are not instructions to protect all those paths in Policies. Their pending
+state contains no `Checking access...` text. They do not provide server SSR
+integration or HTTP status changes. Do not install both a startup check and a
+router gate; do not apply these browser demos to an existing hydrated SSR root.
+
+### Optional browser startup gate for a browser-only app
+
+This alternative is useful only if browser mounting must wait for an access
+check. Skip it when the server already guards HTML and document navigation is
+used. It is not required by either rendering option above.
 
 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
@@ -180,41 +297,582 @@ This is browser code, not a server hook. The startup file can use any framework:
 | 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.
+Client router navigation does not rerun this optional startup file. A UI check
+cannot set the original HTTP status or make public bundles private.
+
+<!-- BEGIN FRONTEND EXAMPLES -->
+
+### Optional SPA demos — choose your frontend implementation
+
+The package includes copyable source files in `examples/frontend`. The same
+examples appear below and in the dashboard frontend selector. Skip this
+section for the default server/document-navigation integration. These are
+optional browser-only demos, not replacements for an existing app or SSR
+entry. Retaining SPA navigation requires asynchronous target checks, even
+for public targets. Pending content is empty; no global checking text is
+required. Keep the target layout hidden until allowed to avoid exposing it
+on denial. Only dashboard rules decide which paths require verification.
+
+If explicitly choosing this mode, merge the relevant hooks into your own
+browser router and adapt the sample paths. Do not add every demo path to
+Policies. Do not combine these gates with the optional startup gate or
+apply them to a hydrated SSR root. SSR uses section 3 and document navigation.
+
+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={null}
+    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
+
+Optional browser-only SPA demo: the service records checking/allowed/denied state. Checks evaluate policy; only dashboard rules require verification. Members uses HttpClient after route access succeeds. Merge providers into your existing browser appConfig. Preserve SSR/hydration with the server/document-navigation option instead of applying this demo to a hydrated root. Modern standalone 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() === 'denied') {
+      <p role="alert">Access unavailable.</p>
+    }
+  `,
+})
+export class App { readonly access = inject(StopneticAccess); }
+```
+
+#### src/angular/app/members.page.ts
 
-### Angular client router, if retaining routerLink
 
 ```ts
 import { isPlatformBrowser } from '@angular/common';
-import { inject, PLATFORM_ID } from '@angular/core';
+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';
 
-export const stopneticRouteGuard: CanActivateFn = async (_route, state) => {
-  if (!isPlatformBrowser(inject(PLATFORM_ID))) return true;
-  // SSR is authorized by the SERVER wrapper above, never by this true value.
-  const result = await checkAccess(state.url.split('#')[0]);
-  if (result.allowed) return true;
-  if (result.reason === 'verification_required' && result.verificationUrl) location.assign(result.verificationUrl);
+@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 === 'denied'" 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 === 'denied'}
+  <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()}>
+      <p role="alert">Access unavailable.</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>;
+}
 ```
 
-Apply `canActivate: [stopneticRouteGuard]` and
-`runGuardsAndResolvers: 'always'` on each page route, including root, or use an
-equivalent parent `canActivateChild` guard. Keep the full header/router/footer
-inside the gated layout. Render a visible unavailable/denied state when a
-navigation is cancelled; returning false alone retains the previous view.
-This guard is UX only. It does not authorize API data or replace server checks.
+#### src/solid/main.tsx
 
-React users may additionally use `StopneticBoundary` from `@stopnetic/js/react`
-inside BrowserRouter around the entire layout; that optional module is not
-required for Angular, Vue, Svelte, Solid or plain JavaScript.
+
+```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();
+  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
 
@@ -258,6 +916,14 @@ 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.
 
+With only `/members` protected, confirm `/about` and `/contact` render without
+a Stopnetic checking screen. Change a dashboard rule and make a new document
+request: the change must apply without editing a client route list. For SSR,
+confirm permitted HTML contains server-rendered page content before JavaScript
+runs, hydration still works, and the renderer is never called on denial. Verify
+the deployed request actually reaches Node; an SSR build alone proves nothing
+about a provider's deployed runtime. Optional SPA checks may have a pending delay.
+
 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
@@ -266,7 +932,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-pilot generated guide is upgraded
+(preview with `--dry-run`). An unchanged 0.0.2/0.0.3/0.0.4 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.