@stopnetic/js 0.0.3-pilot → 0.0.5-pilot

package/README.md

@@ -6,15 +6,20 @@ 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.3-pilot is prepared locally; it is not published yet**. It adds a
-framework-independent generated guide, a complete Node application wrapper
-(`createStopneticAppHandler`) and safe migration of the unchanged older guide.
+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.
 Angular, React, Vue, Svelte, Solid and plain JavaScript share the browser/server
 contracts; no React dependency is required. See the
-[complete generated guide](src/client-guide.md) for SSR, static builds, Angular,
+[complete generated guide](dist/client-guide.md) for SSR, static builds, frameworks,
 client navigation, API protection and runtime restrictions.
 
-The currently published **0.0.2-pilot** adds a reusable browser/server setup for Netlify, Vercel
+The currently published **0.0.4-pilot** 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
 normalizes public PEM formatting and rejects placeholder or reused installation
 keys as cookie secrets. Install the published pilot with:
@@ -23,6 +28,41 @@ keys as cookie secrets. Install the published pilot with:
 npm install @stopnetic/js@pilot
 ```
 
+## Framework implementation examples
+
+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
+and hydration; do not apply the browser demos to an existing SSR root. A runtime
+incompatibility needs a deployment decision, not an automatic conversion to CSR.
+Dashboard policies decide which paths require verification; demo paths are not
+instructions to protect every page. SPA checks still evaluate public targets
+asynchronously and can show a brief empty pending state. The examples are:
+
+| Frontend | Example |
+| --- | --- |
+| React | BrowserRouter, full-layout StopneticBoundary, Routes and effect-based API loading |
+| Angular | Route guard/service, layout signals, RouterOutlet and HttpClient |
+| Vue | Vue Router beforeEach/afterEach, gated App.vue and API loading |
+| Svelte | onMount, History API/popstate navigation and abort cleanup |
+| Solid | Router root, useLocation, reactive Show boundary and API loading |
+| Plain JavaScript | DOM rendering, checked navigation and API loading |
+
+Each example includes initial access, later navigation, verification redirect,
+empty pending content, denied UI and cancellation. Backend page/API guards remain necessary.
+No framework library is added as a required SDK dependency. The generated guide
+embeds the source; use its file paths and helper instructions when copying it.
+The dashboard's frontend selector shows the same files. For maintenance, run
+`npm run build` in this SDK, then `npm run sync:guides` in dashboard.
+
+To rerun the frontend compilation/browser fixtures, build the SDK and run
+`node tests/prepare-framework-tests.mjs` in this directory. This packs the SDK
+and installs pinned test-only libraries inside ignored test-results. Then run
+`.venv/Scripts/python.exe integrations/javascript/tests/framework-browser-check.py`
+from the repository root. The Angular fixture uses an existing Angular install:
+`angular-guide-check.py <project-path>`; it copies source into the workspace,
+compiles the examples and tests browser/Node SSR without changing that project.
+
 For local testing, build and pack from this repository:
 
 ```sh
@@ -31,7 +71,7 @@ npm run build
 npm pack
 ```
 
-Install the resulting `stopnetic-js-0.0.3-pilot.tgz` into the website project using
+Install the resulting `stopnetic-js-0.0.5-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.
@@ -67,7 +107,8 @@ preserved. Vercel configuration is preserved. Put runtime settings in the hostin
 provider's server/Functions environment; plain `netlify.toml` build env is not a
 Functions secret store. Copy the generated cookie secret without committing it.
 
-Wire browser route checks and EACH protected API following the generated guide.
+Wire the server page guard and EACH protected API following the generated guide.
+Browser route checks are optional for retained SPA navigation.
 Run `npm exec --no -- stopnetic-js check` after setting credentials (`--local-http`
 for a loopback pilot). This check validates configuration and generated files
 offline; it cannot prove deployment routing, API coverage or browser integration.
@@ -80,12 +121,11 @@ server environment loader. Production credentials belong in runtime settings.
 
 ### Shared browser startup and Node SSR
 
-The generated [framework-independent guide](src/client-guide.md) gives one
-browser entry that calls `checkAccess` before importing the application's
-existing bootstrap. Keep Angular's bootstrapApplication, React's createRoot,
-Vue's createApp, Svelte's mount, Solid's render or plain DOM startup unchanged
-in that bootstrap module. Use document links for server-checked navigation,
-or recheck target access in the client router. A browser-only check is UI behavior.
+The generated [framework-independent guide](dist/client-guide.md) defaults to
+server document navigation: leave browser startup/layout intact, use normal
+links, and let the server apply dashboard policies. It also gives an OPTIONAL
+browser startup gate and separate OPTIONAL SPA router demos. Do not combine
+the alternatives or apply browser-only gates to an SSR hydration root.
 
 For Node SSR use the generated Express helper before static files/rendering,
 or `createStopneticAppHandler` around a Fetch-style application entry (0.0.3).
@@ -97,15 +137,17 @@ adapted; accepting Request/Response does not make an Edge runtime supported.
 The guide includes Angular SSR/rendering and client router examples. Angular
 SSR compiled with the installed Angular 22 dependencies and served real HTML
 after verification in an isolated local fixture. That does not validate a live
-provider deployment. Netlify's automatic Angular SSR uses Edge; choose Node SSR,
-a Node gateway or a deliberate static build. Do not publish protected prerendered
+provider deployment. Netlify's automatic Angular SSR uses Edge; the Node SDK
+has no drop-in integration for that runtime. Preserve SSR and obtain a supported
+Node deployment/gateway decision instead of silently converting the app. Do not publish protected prerendered
 HTML. For other frameworks use the same Node server entry and verify their
 actual deployed runtime. React's boundary remains an optional convenience.
 
 ### Optional React Router boundary
 
 The optional React entry uses Hooks. The core/browser modules need no React.
-Place this component inside BrowserRouter, wrapping your Routes:
+Use this only for explicitly retained browser SPA navigation, inside BrowserRouter,
+around the full target layout. Server document navigation does not require it:
 
 ```jsx
 import { useLocation } from 'react-router-dom';
@@ -113,11 +155,12 @@ import { StopneticBoundary } from '@stopnetic/js/react';
 
 function RouteGuard({ children }) {
   const location = useLocation();
-  return <StopneticBoundary path={location.pathname + location.search}>
+  return <StopneticBoundary path={location.pathname + location.search} pending={null}>
     {children}
   </StopneticBoundary>;
 }
-// <BrowserRouter><RouteGuard><Routes>...</Routes></RouteGuard></BrowserRouter>
+// <BrowserRouter><RouteGuard><Layout/></RouteGuard></BrowserRouter>
+// Layout includes the target header, routes and footer.
 ```
 
 The boundary hides children while checking, ignores canceled/stale checks and