@plitzi/sdk-server 0.38.3 → 0.38.5

package/README.md

@@ -4,8 +4,9 @@ The page server for Plitzi spaces: server-side rendering, React Server Component
 HTTP kernel they run on. Ships as an HTTP/2 server by default, with support for HTTP/1.1 and HTTP/3.
 
 This package serves **pages**. The AI surface — the MCP server, its tool engine and the draft-preview
-endpoint — lives in [`@plitzi/sdk-mcp`](../mcp/README.md), which builds on this one. A deployment that only
-renders pages never installs it, and never loads it.
+endpoint — lives in [`@plitzi/sdk-mcp`](../mcp/README.md), which depends on this one's narrow entries (the kernel,
+OAuth, and the renderer for draft preview alone), never the other way round. A deployment that only renders pages
+never installs it, and never loads it.
 
 ## Installation
 
@@ -158,16 +159,21 @@ serve it — worth running over anything that arrives as a file.
 A space on Plitzi comes out whole, as a project wired to this server: `npx @plitzi/cli create my-site --from <space>`
 writes its pages as authoring code, its actions as `defineAction` code, its functions, the source of its plugins and
 runtime, and its files into `public/` — a draft, or any published snapshot (`--environment`, `--revision`) — and
-`plitzi pull` keeps it in step. See `docs/en/projects-from-spaces.md` in the workspace.
+`plitzi pull` keeps it in step, and `plitzi push` puts what changed in it back on the space. See
+`docs/en/projects-from-spaces.md` in the workspace.
 
 ## Configuration
 
+`createServer` takes a `ServerConfig` (exported, as a type, from `@plitzi/sdk-server`) — what a project types its own
+options with: a `plitzi create` project keeps them in `src/config/serverOptions.ts`, typed from it less what its `main.ts`
+wires itself.
+
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `httpVersion` | `1 \| 2 \| 3` | `2` with `tls`, else `1` | HTTP protocol version. Falls back to the nearest available lower version. |
 | `tls` | `{ key, cert, minVersion? }` | — | TLS key and certificate. Required for versions 2 and 3; optional for version 1. |
 | `devMode` | `boolean` | `false` | Enables development mode: appends `?dev` to esm.sh CDN URLs for React, and activates per-request timing metrics (see [Dev metrics](#dev-metrics)). Off, the process must run with `NODE_ENV=production` or React renders with its development build; the server says so once, at `error`. |
-| `devReload` | `boolean` | `false` | Every page this server renders listens for `server.reloadPages()` and loads again — for a project that re-authors its space on save (what `plitzi create` writes into `main.ts`). Not turned on by `devMode`: each open page holds a connection for it. |
+| `devReload` | `boolean` | `false` | Every page this server renders listens for `server.reloadPages()` and loads again — for a project that re-authors its space on save (what `plitzi create` writes into `main.ts`) — and loads again too when it reconnects to a server that restarted (a new process), so a change to the server's code reaches the open page. With `devMode` too, a plugin whose source changes is built again and swapped where it is drawn on every open page — the rest of the page, its state included, stays as it was; a plugin whose declaration changed loads the page again. Not turned on by `devMode`: each open page holds a connection for it. |
 | `assetVersion` | `string` | — | Cache-buster appended as `?v=<assetVersion>` to all default SDK asset URLs. Compute from file mtime or package version at startup. |
 | `cacheTtlMs` | `number` | `300000` | TTL in milliseconds for the SSR render cache. Set to `0` to disable. |
 | `flags` | `Record<string, boolean> \| ({ spaceId, environment }) => Record<string, boolean>` | — | This deployment's say over the spaces' feature flags: above what a space declares, below the SDK's `flags` prop and a tester's dev tools, and only for flags the space declares. A function answers per space. Server actions and RSC resolve with it too. See `docs/en/feature-flags.md` in the workspace. |
@@ -176,11 +182,12 @@ runtime, and its files into `public/` — a draft, or any published snapshot (`-
 | `signIn` | `SSRSignInConfig` | — | Sign visitors in by redirect through an OAuth 2.1 authorization server: `GET /auth/sign-in?return=/x` registers this host as a client, sends the browser out with PKCE (state in a `__Host-` cookie), and `/auth/sign-in/callback` redeems the code server to server and hands the token to `exchangeCredential`, which makes the session here. Needs the `exchangeCredential` adapter. |
 | `templateFn` | `SSRTemplateFn` | built-in EJS template | Custom render function. Receives all template params and returns an HTML string. |
 | `plugins` | `Record<string, PluginSource>` | — | Named plugin definitions. Compiled or copied on first use and cached for `pluginsTtlMs`. |
-| `pluginsCacheDir` | `string` | `.sdk-plugins` | Directory where compiled plugin files are stored. |
+| `pluginsCacheDir` | `string` | `tmp/.sdk-plugins` | Directory where compiled plugin files are stored — under `tmp/`, with everything else the server writes for itself. |
 | `pluginsTtlMs` | `number` | `604800000` | TTL in milliseconds for compiled plugins (default: 1 week). |
 | `autoLoadSchemaPlugins` | `boolean` | `true` | Auto-download and cache plugins declared in the schema's `offlineData.plugins` list. A type the deployment registers itself (`plugins`, named in `pluginNames`) is never looked for there: its own build is the one rendered. Set to `false` to manage plugin loading manually. |
 | `allowPrivatePluginHosts` | `boolean` | `false` | Read a schema plugin from a private address (`localhost`, this server's own network). A plugin's address is typed by whoever edits a space, so leave it off anywhere but a development machine whose bucket is local. |
-| `publicDir` | `string` | — | Absolute path to a directory served at the root URL level (e.g. `robots.txt`, `favicon.png`). Files are checked before `static` prefix routes. |
+| `publicDir` | `string` | — | Absolute path to a directory served at the root URL level (e.g. `robots.txt`, `favicon.png`). Files are checked before `static` prefix routes. **Everything in it is public:** served to anyone who asks, with no check. |
+| `dataDir` | `string` | — | The project's own data, never served: a provider resolved on the server (`runtime: 'server'`) whose `query` is `/data/<file>` reads `<dataDir>/<file>`. See [Project data](#project-data). |
 | `static` | `Record<string, string>` | — | URL prefix → filesystem path mappings for static file serving. |
 | `images` | `{ domains, cacheDir? }` | — | Pictures from other sites resized at `/_plitzi/img`, for an `image` to offer as a `srcset` (see [Images](#images)). |
 | `ssrOnly` | `boolean` | `false` | Omit client-side JS from the rendered page. Useful for verifying SSR HTML without hydration. |
@@ -195,6 +202,20 @@ runtime, and its files into `public/` — a draft, or any published snapshot (`-
 | `logger` | `ServerLogger` | the console | Where it says it: one structured `ServerLogEvent` stream. `consoleLogger` prints each as one line. |
 | `onListenError` | `(error, { port, host, label }) => void` | exits non-zero | What to do when the server cannot take its port. By default it prints what went wrong and what to do about it, then exits — a process whose server never bound is not running. Supply this to keep it alive and decide yourself. |
 | `workers` | `boolean \| number \| 'auto'` | `'auto'` under `NODE_ENV=production`, else `false` | How many processes serve the port: one per core, a number (lowered to the cores there are), or one. `SDK_SERVER_WORKERS` sets it when the config does not. See [Using every core](#using-every-core). |
+| `action` | `SSRActionConfig` | — | The space's server actions: the write endpoint (`path`, default `/_action`), `lookups` (`ActionLookupsConfig`: `getAction`, `getFunctions`, `getPluginFunctions`, `getData`…), `kv`, `jobs`, `limits`, `email`, `signingSecret`, `onRun` / `onReject`. Absent, the server serves reads only. See `docs/en/server-actions.md` § 13 in the workspace. |
+| `functions` | `{ native?, plugins?, runner?, limits? }` | — | The server's code (`FunctionsConfig` in `@plitzi/sdk-server/functions`, checked as the server starts): its own tasks and routes (`native`, from `loadFunctions`), the server halves of the plugins it ships (`plugins`, by plugin type — see [A plugin's server half](#a-plugins-server-half)), the `runner` the spaces' functions run on, and the per-invocation `limits`. See `docs/en/functions.md` § 8 in the workspace. |
+| `connectors` | `ConnectorLookupsConfig` | — | `getConnector` and `getCredential` for the space's connectors, read by the RSC read path and the `/_action` write endpoint alike. See `docs/en/connectors.md` in the workspace. |
+| `auth` | `Auth` | — | A `createAuth(...)` result: fills the three auth adapters in and brings the cookie naming. See [User authentication](#user-authentication). |
+| `sessionRenewal` | `{ url } \| false` | on with `auth` | Where a page request whose access cookie died, its refresh cookie alive, renews before it is rendered. |
+| `authCookie` | `SSRAuthCookie` | — | Name, domain, `sameSite`, `secure`, `refreshPath` (`/auth`) and `hintSuffix` (`_hint`) of the session cookies. `auth` brings its own; set here, a piece wins over it. |
+| `exchangePath` | `string \| false` | `'/auth/exchange'` | Where a browser-obtained credential is handed over; served only with the `exchangeCredential` adapter. |
+| `debugMode` | `boolean` | `devMode`, or the space's `devTools` | Authorizes debugging on the pages this server renders. Set, it decides for every space: `false` is a refusal no space turns around. |
+| `frameOptions` | `'DENY' \| 'SAMEORIGIN' \| string[] \| false` | `'DENY'` | Who may embed the pages in a frame (CSP `frame-ancestors`, and `X-Frame-Options`); `false` omits both headers. A space adapter's `frameAncestors` derives it per space — see [Space adapters](#space-adapters-a-space-per-domain). |
+| `fonts` | `{ baseUrl?, dir? }` | `baseUrl: '/fonts'` | Where the font files a space uploaded are addressed, and with `dir` served from this server under `/fonts/*`. See `docs/en/fonts.md` in the workspace. |
+| `environment` | `'production' \| 'staging' \| 'development' \| 'local'` | `'production'` | The Plitzi tier whose endpoints the rendered pages are handed. |
+| `services` | `{ ssr?, rsc? }` | `ssr` on, `rsc` with `getRscData` | Which request-handling services are mounted. |
+| `preview` / `draftStore` | `SSRPreviewConfig` / `DraftStore` | off / in memory | The draft-preview endpoint (`enabled`, `path` `/__preview`, `secret`, `ttlMs`) and the store behind its tokens — share one across replicas. The rest of draft preview is `@plitzi/sdk-mcp`'s: see its [Draft preview](../mcp/README.md#draft-preview). |
+| `port` / `host` | `number` / `string` | — | Not read: `server.listen(port, host?)` takes where it binds (`host` defaults to `0.0.0.0`). |
 
 ### HTTP version behaviour
 
@@ -296,13 +317,17 @@ const server = createServer({
 server.listen(3001);
 ```
 
+Beside the page adapters it offers `getSchema` and `getStyle`, read from the same file, and — when `offlineData` is a
+path — `saveSchema` and `saveStyle`, each writing its document back into the file. So an MCP server
+([`@plitzi/sdk-mcp`](../mcp/README.md#adapters)) can run over it, with a `getGrant` of yours beside it.
+
 ### `JsonAdaptersConfig`
 
 | Option | Type | Description |
 |---|---|---|
 | `offlineData` | `string` | Path to a single JSON file used for every request. |
 | `offlineData` | `(spaceId, environment, revision?) => string` | Function returning the path for the requested space. |
-| `offlineData` | `OfflineDataRaw` | The space itself, for a consumer that already holds it. Read-only: `saveOfflineData` is offered only for a path. |
+| `offlineData` | `OfflineDataRaw` | The space itself, for a consumer that already holds it. Read-only: `saveSchema` and `saveStyle` are offered only for a path. |
 | `deployment` | `string` | Path to a JSON file containing an `SSRSpaceDeployment` object. |
 | `deployment` | `SSRSpaceDeployment` | Inline deployment object used for every request. |
 | `deployment` | `Record<hostname, SSRSpaceDeployment>` | Per-hostname map. Use `'*'` as a catch-all. |
@@ -397,11 +422,13 @@ createServer({ images: { domains: ['images.example.com', '*.cdn.example.com'] },
 
 An `image` whose `src` is another site's then offers the browser a `srcset` of widths this server makes (320 to 1920
 px) at `/_plitzi/img?url=…&w=…`, in AVIF or WebP when the browser takes them. Everything is kept on disk (`cacheDir`,
-default `.plitzi/images`): each original is downloaded once, and each size is made once from it. A week on, the kept
+default `tmp/images`): each original is downloaded once, and each size is made once from it. A week on, the kept
 files keep answering while the original is asked for with its `ETag` / `Last-Modified` — unchanged, nothing is resized
 again; changed, its sizes are made anew. A picture that could not be fetched is not asked for again for five minutes.
 Only the listed hosts are fetched, every redirect is held to the same
-list and to the rule every outbound request follows (no private network), and SVG is refused. Resizing needs `sharp`
+list and to the rule every outbound request follows (no private network). An SVG is never resized nor served from
+this origin: the proxy answers it with a redirect to its own address (`307`), so the picture still shows. An `image`
+with `resize: false` keeps its `src` as written. Resizing needs `sharp`
 (an optional peer): without it pictures are passed through and kept, and the server says so once.
 
 ### Public directory
@@ -417,8 +444,30 @@ createServer({
 
 The lookup order for a request is: `publicDir` → `static` prefix routes → SSR renderer.
 
+**Everything in `publicDir` is on the internet.** A file there is served to anyone who asks for it, as it is — no
+session, no permission, no check. Never put a secret, a key, an `.env`, a private document, a database dump or data only
+some visitors may read in it: that is served by a server action whose `access` checks who is asking.
+
 `/.well-known/` paths follow the same lookup order: served from `publicDir` if a matching file exists, otherwise `404 Not Found`. They are never handled by the SSR renderer.
 
+### Project data
+
+A project with no backend keeps its data as JSON files, and `dataDir` is where they stay off the internet: nothing
+serves the folder. A provider resolved on the server whose `query` is `/data/<file>` reads `<dataDir>/<file>` before the
+page is answered — in the shape a browser request publishes (`{ status, data }`), so a binding reads `<source>.data.…`
+in either runtime — and the page arrives with it. A browser asking for the same path gets a page, never the file.
+
+```ts
+createServer({ dataDir: path.join(PROJECT_ROOT, 'src/data'), adapters: { ... } });
+```
+
+Without a `dataDir`, `/data/<file>` is answered from `action.lookups.getData(spaceId, at)` — the space's own data, as
+its files' text by path, as of the version being rendered: what a cloud deployment keeps for a space (`plitzi push`).
+
+`/data/…` is the data folder's first; a server provider reading another path is answered from `publicDir`, as the
+browser would be. What a provider reads goes into the page it renders, whole: data a page must not carry — a price
+list's costs, another visitor's rows — is a server action's to read, answering only what is shown.
+
 ## Compression
 
 Responses are compressed based on the `Accept-Encoding` request header. By default the server offers Brotli, then
@@ -510,15 +559,19 @@ All fields are optional and combined with AND logic. Calling `invalidate()` with
 
 Plugins are React component bundles that extend the Plitzi schema renderer. They are defined globally at server config level, compiled or copied on first use, and cached on disk for one week. The `getSpaceDeployment` adapter controls which plugins each space gets access to via `pluginNames`.
 
+A compiled plugin is one module and its stylesheet, built as `plitzi pack plugin` builds it: React and the SDK kept out, and everything else inside — images and fonts as data URIs, and a file imported whole the way Vite imports it (`worker.js?raw` for its text, `engine.wasm?inline` for a data URI).
+
+Whatever stylesheet the server writes for a plugin — compiled, copied or downloaded — goes into the `plitzi-sdk-plugin` cascade layer (`inPluginLayer` from `@plitzi/sdk-shared/style`), below the space's own: a space's classes and `customCss` win over what the plugin shipped, whatever the specificity. A `css` given as a web path (`/builder-assets/…`) is linked as it is.
+
 ```ts
-import type { SSRSpaceDeployment } from '@plitzi/sdk-server';
+import type { SSRSpaceDeployment } from '@plitzi/sdk-shared';
 
 const server = createServer({
   plugins: {
     // From a source file — compiled to ESM with esbuild
     'my-chart': {
       js: '/abs/path/to/MyChart.tsx',
-      css: '/abs/path/to/MyChart.css',  // filesystem path — copied to .sdk-plugins
+      css: '/abs/path/to/MyChart.css',  // filesystem path — copied to tmp/.sdk-plugins
       version: '1.2.0'
     },
     // Pre-compiled local file — copied as-is (version defaults to '1.0.0')
@@ -637,6 +690,10 @@ Compiled and copied plugin files are served under `/sdk-plugins/{name}/`:
 
 Plugin responses are compressed with Brotli or gzip like all other responses.
 
+A page imports only the plugins it draws: its own elements, its layouts', and those of the components and references it
+holds (`pageElementTypes`). The rest reach the page as their declaration (`PluginEntry.deferred`) and are imported when
+a page that draws them is opened, client-side navigation included.
+
 ### TTL and invalidation
 
 Plugins are compiled once and cached for `pluginsTtlMs` (default: 1 week). The TTL is tracked via a `meta.json` file written alongside each plugin's compiled output. On the next request after expiry the plugin is automatically recompiled.
@@ -665,13 +722,37 @@ server.plugins.register('my-chart', {
 
 `register` clears any in-memory cache for that plugin name, so the next request triggers a fresh compile/copy. Previously compiled disk files are reused if they are within their TTL; call `server.plugins.invalidate(name)` beforehand to force a full rebuild.
 
+### A plugin's server half
+
+A plugin can bring server code — its `functions/`, written as a space's functions are — whose routes answer under
+`/fn/plugins/<type>/` and whose tasks are steps named `<type>.<action>`, run with a plugin's narrower `ctx` (its own
+corner of `kv`, none of the space's credentials or channels). This server's own plugins hand theirs over by type:
+
+```ts
+import { createServer, loadFunctions } from '@plitzi/sdk-server';
+
+const [board] = await loadFunctions(new URL('./plugins/Board/functions/', import.meta.url));
+
+const server = createServer({ adapters, functions: { native, plugins: { board } } });
+
+// While it runs: a server half loaded again — or, with none, taken away — without a restart.
+server.functions.setPlugin('board', board);
+```
+
+`loadFunctionsSource(files)` loads one from its files rather than a folder: what a packed plugin carries as
+`functions.source.json`. The plugins a space uploaded reach a run through `action.lookups.getPluginFunctions`. The
+whole of it — `ctx`, routes, how a packed plugin carries it — is in
+[functions § a plugin's server half](../../docs/en/functions.md#10-a-plugins-server-half).
+
 ## React Server Components (RSC)
 
 The SSR server includes a lightweight RSC endpoint that delivers server-side data to schema elements with `runtime: 'server'`. This is not the React RSC wire protocol — it uses a simple JSON transport that any element can consume via `useRscData()`.
 
 ### Schema setup
 
-Enable RSC at the top level of your schema:
+Server data is on unless the schema turns it off with `"rsc": { "enabled": false }` — the page render and the
+default `getRscData` (`connectorRscData`) read a missing `rsc` alike. `authorSpace` writes it out for a space with a
+server provider:
 
 ```json
 {
@@ -710,7 +791,7 @@ Implement `getRscData` in your adapters to serve data from the `/_rsc` endpoint.
 When `ids` is provided the client is performing a **partial refresh** — only return data for those element IDs. When `ids` is absent, return data for all elements (full fetch):
 
 ```ts
-import type { SSRAdapters, SSRRscContext, SSRRscData } from '@plitzi/sdk-server';
+import type { SSRAdapters, SSRRscContext, SSRRscData } from '@plitzi/sdk-shared';
 
 const getRscData = async ({ user, ids, loadOfflineData }: SSRRscContext): Promise<SSRRscData> => {
   // Only serve data when the schema has RSC enabled. `loadOfflineData` joins the read the page render already
@@ -773,6 +854,10 @@ type SSRRscData = {
 
 Return `{}` (empty object) when there is no server data for the current request. Each key must match the `id` of a schema element with `runtime: 'server'`.
 
+**One request per question, the newest winning.** The client (`refreshRsc`) joins a refresh already in flight for the same URL, and aborts one a newer refresh would overwrite — a whole payload asked again, an element asked again — so answers never land out of order. `cancelRsc(store, ids)` (an `apiContainer`'s `cancelQuery`) aborts on purpose. The server hears it: `SSRRscContext.signal` aborts when the browser hangs up, and the default `getRscData` stops every element still resolving — an action's render run included, unless another visitor's identical render is still waiting on the same run. A custom adapter does the same with the signal it is handed.
+
+What a refresh asks for besides the location (`/_rsc?location=…&country=fr`) is `req.ctx.rscParams`; the action resolver hands it to the action over the `input` the element was saved with.
+
 ### `/_rsc` endpoint
 
 The server automatically registers `GET /_rsc` when `adapters.getRscData` is provided. The endpoint:
@@ -780,7 +865,7 @@ The server automatically registers `GET /_rsc` when `adapters.getRscData` is pro
 1. Reads `spaceId`, `environment`, and `revision` from the resolved `spaceDeployment` context.
 2. Reads the authenticated user from `ctx.user`.
 3. Reads optional `?ids=elem1,elem2` for partial refresh.
-4. Calls `adapters.getRscData({ req, spaceId, environment, revision, user, ids, loadOfflineData })`.
+4. Calls `adapters.getRscData({ req, spaceId, environment, revision, user, ids, loadOfflineData, signal })`.
 5. Returns a JSON payload:
 
 ```json
@@ -815,6 +900,7 @@ createServer({
 | `enabled` | `boolean` | `true` (when adapter provided) | Activate or deactivate the RSC endpoint. |
 | `path` | `string` | `'/_rsc'` | URL path for the RSC endpoint. |
 | `cacheTtlMs` | `number` | `30000` | TTL in milliseconds for the RSC response cache. Set to `0` to disable RSC caching. Ignored for the `main` environment. |
+| `elementTimeoutMs` | `number` | `5000` | How long one server element may take before the page is answered without it — and what it was resolving is cancelled. The page's ceiling, winning over the producer's own (`action.limits.timeoutMs`). A section cut by it says to raise this. |
 
 ### Consuming RSC data in plugins
 
@@ -1109,7 +1195,7 @@ Credential comparison uses `crypto.timingSafeEqual` to prevent timing attacks. I
 Register request-scoped middleware to run before the SSR renderer. Middlewares execute in the order they are declared and can short-circuit by not calling `next()`.
 
 ```ts
-import type { SSRMiddleware } from '@plitzi/sdk-server';
+import type { SSRMiddleware } from '@plitzi/sdk-shared';
 
 const corsMiddleware: SSRMiddleware = (req, res, next) => {
   res.setHeader('Access-Control-Allow-Origin', 'https://app.example.com');
@@ -1243,7 +1329,9 @@ ends any other event stream, lets what is being answered finish, and cuts whatev
 (`SHUTDOWN_GRACE_MS`). A page left open on a board, or an agent's app listening, no longer holds a Ctrl+C or a
 SIGTERM until something kills the process.
 
-`@plitzi/sdk-server/mysql` has the same pair over a `mysql2` pool (`createMysqlJobQueue`, `createMysqlKv`). Anything
+`@plitzi/sdk-server/mysql` has the same pair over a `mysql2` pool (`createMysqlJobQueue`, `createMysqlKv`). With no
+database at all, `kv` survives a restart in a file: `createFileKv` (`@plitzi/sdk-server/actions`, one process, JSON) or
+`createSqliteKv` (`@plitzi/sdk-server/sqlite`, any number of processes on the file). Anything
 else is the `ActionJobQueue` contract written against your store — see
 [server actions § self-hosted](https://github.com/plitzi/plitzi-workspace/blob/main/docs/en/server-actions.md#13-for-a-self-hosted-deployment).
 
@@ -1299,7 +1387,7 @@ URLs become `/sdk-assets/plitzi-sdk.js?v=<assetVersion>`. This is separate from
 By default the server uses its built-in EJS template. You can replace it with any function that receives the template params and returns an HTML string:
 
 ```ts
-import type { SSRTemplateFn } from '@plitzi/sdk-server';
+import type { SSRTemplateFn } from '@plitzi/sdk-shared';
 
 const templateFn: SSRTemplateFn = ({ html, offlineData, jsPath, cssPath, plugins, react, reactDom, reactDomClient, reactJsx }) => `
   <!doctype html>
@@ -1322,6 +1410,16 @@ createServer({ templateFn, adapters: { ... } });
 
 The function is called once per render (cache misses only). The built-in `template.ejs` is used as fallback when `templateFn` is not set.
 
+What the built-in template does that a custom one has to decide for itself:
+
+- **The space travels beside the page.** The built-in template leaves it out of the payload, names it with
+  `spaceDocumentPath` (`<link id="plitzi-space" rel="preload" as="fetch">`) and its bootstrap fetches it before it
+  hydrates. A custom template is handed the space inline in `offlineData`, as before.
+- **Only the plugins the page draws are imported up front.** An entry with `deferred` is handed to `render()` as
+  `{ load: () => import(js), css, declaration }`: the SDK registers it at once and loads its code and stylesheet the
+  first time one of its elements is drawn. A template that imports every entry statically still works; it only loads
+  more than the page draws.
+
 **Streaming compatibility**: when `streaming: true` the server calls `templateFn` with a sentinel placeholder (`<!--SSR_CONTENT-->`) in place of the React HTML, splits the output at that marker, and streams head and tail separately. Existing templates that interpolate `html` as-is are compatible without any changes.
 
 ## Template props
@@ -1346,9 +1444,11 @@ return {
 | `title` | `string` | Page `<title>`. Defaults to `'Plitzi App'`. |
 | `jsPath` | `string` | URL for the SDK JS module. Defaults to `/sdk-assets/plitzi-sdk.js`. |
 | `cssPath` | `string` | URL for the SDK stylesheet. Defaults to `/sdk-assets/plitzi-sdk.css`. |
+| `iconsCssPath` | `string` | URL for Font Awesome's stylesheet, linked after `cssPath`; its fonts are files beside it. Defaults to `/sdk-assets/plitzi-sdk-icons.css`. |
+| `spaceDocumentPath` | `string` | Where the page fetches the space from (`/_plitzi/space/<hash>.json`), preloaded in the head and read by the bootstrap before it hydrates. Set by the built-in template's render; absent for a draft preview and for a custom `templateFn`, which receive the space inline in `offlineData`. |
 | `builderJsPath` | `string` | URL for the builder JS module. Omitted by default. |
 | `builderCssPath` | `string` | URL for the builder stylesheet. Omitted by default. |
-| `plugins` | `PluginEntry[]` | Plugin entries to inject. Normally set automatically via `pluginNames`. |
+| `plugins` | `PluginEntry[]` | Plugin entries to inject. Normally set automatically via `pluginNames`. An entry with `deferred` is one the page draws none of: its declaration, for the browser to load its code when a page that draws it is opened. |
 | `react` | `string` | React ESM URL. Defaults to `esm.sh/react@19`. |
 | `reactDom` | `string` | ReactDOM ESM URL. |
 | `reactDomClient` | `string` | ReactDOM client ESM URL. |
@@ -1438,6 +1538,27 @@ package, not a snippet.
 
 ## Exported types
 
+What this package's own code defines is exported from it:
+
+```ts
+import type {
+  ServerConfig,
+  SSRContext,
+  PipelineExtensions,
+  JsonAdaptersConfig,
+  AuthAdapters,
+  AuthAdaptersConfig,
+  CloudAdaptersConfig,
+  SpaceAdaptersConfig
+} from '@plitzi/sdk-server';
+```
+
+`ServerConfig` is what `createServer` takes — `SSRServerConfig` with the page adapters required, plus `auth` and
+`sessionRenewal` — and what a project types its own options with. `SSRContext` here is the request context a pipeline
+stage sees.
+
+The shapes the server shares with the SDK and `@plitzi/sdk-mcp` are `@plitzi/sdk-shared`'s:
+
 ```ts
 import type {
   SSRAdapters,
@@ -1446,13 +1567,13 @@ import type {
   SSRResponseHelpers,
   SSRMiddleware,
   SSRMiddlewareNext,
-  SSRContext,
   SSRSpaceDeployment,
   SSRTemplateProps,
   SSRTemplateFn,
   SSRCredential,
   SSRUser,
   SSRHeaders,
+  SSRRscContext,
   SSRRscData,
   SSRRscConfig,
   SSRServer,
@@ -1463,9 +1584,6 @@ import type {
   PluginEntry,
   PluginRegistry,
   CacheFilter,
-  CacheManager,
-  JsonAdaptersConfig,
-  AuthAdapters,
-  AuthAdaptersConfig
-} from '@plitzi/sdk-server';
+  CacheManager
+} from '@plitzi/sdk-shared';
 ```

package/dist/actions.d.ts

@@ -41,18 +41,21 @@ export { checkAction } from './modules/actions/runtime/check';
 export type { ActionCheckDeps } from './modules/actions/runtime/check';
 export { ActionRefusal, ActionRunError } from './modules/actions/runtime/errors';
 export { DEFAULT_LIMITS } from './modules/actions/runtime/limits';
+export { MIN_SIGNING_SECRET_LENGTH } from './modules/actions/runtime/signing';
 export { createTaskRegistry, taskName } from './modules/actions/tasks/registry';
 export { describeCatalog, describeTask } from './modules/actions/taskCatalog';
 /**
  * The `kv` seam: an ADAPTER a deployment fills, and the logic that sits on top of it.
  *
- * There is deliberately nothing here that talks to a store — no Redis, no database, no client of any kind. A
- * deployment passes five string operations over whatever it already runs, and `createKvStore` supplies everything
- * that decides how a counter behaves, so the rule a rate limit depends on is written once rather than once per
- * deployment. The in-process Map is the same shape, which is why the default and a cluster's store behave
- * identically instead of nearly so.
+ * There is deliberately no client of any store here: a deployment passes six string operations over whatever it
+ * already runs (`createRedisKv` wraps a client it opened), and `createKvStore` supplies everything that decides how a
+ * counter behaves, so the rule a rate limit depends on is written once rather than once per deployment. The
+ * in-process Map is the same shape, which is why the default and a cluster's store behave identically instead of
+ * nearly so — and `createFileKv` is that Map kept in a JSON file, for one process that must survive a restart.
  */
 export { createMemoryKv } from './modules/actions/runtime/memoryKv';
+export { createFileKv } from './modules/actions/runtime/fileKv';
+export type { FileKv, FileKvOptions } from './modules/actions/runtime/fileKv';
 export { createKvStore } from './modules/actions/runtime/kvStore';
 export { createRedisKv } from './modules/actions/runtime/redisKv';
 export type { RedisKvClient, RedisKvOptions } from './modules/actions/runtime/redisKv';

package/dist/actions.js

@@ -9,11 +9,13 @@ import { createKvStore } from "./modules/actions/runtime/kvStore.js";
 import { DEFAULT_LIMITS } from "./modules/actions/runtime/limits.js";
 import { createMemoryKv } from "./modules/actions/runtime/memoryKv.js";
 import { spaceKvPatterns } from "./modules/actions/runtime/namespaceKv.js";
+import { MIN_SIGNING_SECRET_LENGTH } from "./modules/actions/runtime/signing.js";
 import { createTaskRegistry, taskName } from "./modules/actions/tasks/registry.js";
 import { checkAction } from "./modules/actions/runtime/check.js";
 import { createRejectLogger, createRunLogger } from "./modules/actions/runtime/runLogger.js";
 import { describeCatalog, describeTask } from "./modules/actions/taskCatalog.js";
 import { createActionsModule } from "./modules/actions/index.js";
+import { createFileKv } from "./modules/actions/runtime/fileKv.js";
 import { createRedisKv } from "./modules/actions/runtime/redisKv.js";
 import { cronFiresBetween, cronMatches, cronNextFire, parseCron } from "@plitzi/sdk-shared/actions";
-export { ActionRefusal, ActionRunError, DEFAULT_LIMITS, DEFAULT_MAX_ATTEMPTS, MAX_LIST_BYTES, MAX_LIST_ENTRIES, checkAction, createActionJobs, createActionsModule, createJobWorker, createKvStore, createMemoryJobQueue, createMemoryKv, createRedisKv, createRejectLogger, createRunLogger, createScheduler, createTaskRegistry, cronFiresBetween, cronMatches, cronNextFire, describeCatalog, describeTask, parseCron, scheduleFor, scheduleJobId, schedulesFor, spaceKvPatterns, taskName };
+export { ActionRefusal, ActionRunError, DEFAULT_LIMITS, DEFAULT_MAX_ATTEMPTS, MAX_LIST_BYTES, MAX_LIST_ENTRIES, MIN_SIGNING_SECRET_LENGTH, checkAction, createActionJobs, createActionsModule, createFileKv, createJobWorker, createKvStore, createMemoryJobQueue, createMemoryKv, createRedisKv, createRejectLogger, createRunLogger, createScheduler, createTaskRegistry, cronFiresBetween, cronMatches, cronNextFire, describeCatalog, describeTask, parseCron, scheduleFor, scheduleJobId, schedulesFor, spaceKvPatterns, taskName };

package/dist/adapters/jsonAdapters.d.ts

@@ -7,7 +7,7 @@ export type JsonAdaptersConfig = {
     /**
      * The space: a path to a `{ schema, style }` JSON, a function returning one per request, or the data itself for a
      * consumer that already holds it (composed at startup, fetched once, built in a test). Only a path can be written
-     * back to, so `saveOfflineData` is offered only when one was given.
+     * back to, so `saveSchema` and `saveStyle` are offered only when one was given.
      */
     offlineData: OfflineDataRaw | string | ((spaceId: number, environment: string, revision?: number) => string);
     deployment?: string | SSRSpaceDeployment | Record<string, SSRSpaceDeployment>;

package/dist/adapters/jsonAdapters.js

@@ -38,13 +38,21 @@ var createJsonAdapters = (config) => {
 			return Promise.resolve(void 0);
 		}
 	};
-	const saveOfflineData = (spaceId, environment, data) => {
+	const getSchema = async (spaceId, environment) => (await getOfflineData(spaceId, environment))?.schema;
+	const getStyle = async (spaceId, environment) => (await getOfflineData(spaceId, environment))?.style;
+	const writeBack = (spaceId, environment, change) => {
 		const filePath = pathFor(spaceId, environment);
 		if (!filePath) return Promise.resolve();
-		writeFileSync(filePath, JSON.stringify(data, null, 2));
+		const current = json.read(filePath);
+		writeFileSync(filePath, JSON.stringify({
+			...current,
+			...change
+		}, null, 2));
 		json.forget(filePath);
 		return Promise.resolve();
 	};
+	const saveSchema = (spaceId, environment, schema) => writeBack(spaceId, environment, { schema });
+	const saveStyle = (spaceId, environment, style) => writeBack(spaceId, environment, { style });
 	const getSpaceDeployment = (req) => {
 		const { deployment } = config;
 		if (!deployment) return Promise.resolve({
@@ -72,7 +80,12 @@ var createJsonAdapters = (config) => {
 	return {
 		getOfflineData,
 		getSpaceDeployment,
-		...typeof config.offlineData !== "object" ? { saveOfflineData } : {}
+		getSchema,
+		getStyle,
+		...typeof config.offlineData !== "object" ? {
+			saveSchema,
+			saveStyle
+		} : {}
 	};
 };
 //#endregion

package/dist/core/configSeam.js

@@ -22,6 +22,10 @@ var isManifest = checkedOnce(isConnectorManifestDraft);
 var isDocument = checkedOnce(isActionDocument);
 /** What `getFunctions` answers: built by `@plitzi/sdk-server/functions` from a space's saved bundle, a live object. */
 var isSpaceFunctions = (value) => isRecord(value) && isRecord(value.bundle) && typeof value.bundle.id === "string" && typeof value.bundle.load === "function" && isRecord(value.manifest);
+/** What `getPluginFunctions` answers: a `SpaceFunctions` per plugin type. */
+var isPluginFunctions = (value) => isRecord(value) && Object.values(value).every(isSpaceFunctions);
+/** What `getData` answers: the space's data files' text, by path. */
+var isProjectData = (value) => isRecord(value) && Object.values(value).every((text) => typeof text === "string");
 /** Why a document is not one this server runs: the first problem its validator found, by where it is. */
 var firstProblem = (errors) => {
 	const first = errors.at(0);
@@ -63,7 +67,7 @@ var connectorLookupsOf = (config) => {
 * not one is refused; listed, it is left out and said, so one broken action does not take its space's schedule down.
 */
 var actionLookupsOf = (config) => {
-	const { getConnector, getFunctions, listActions } = config;
+	const { getConnector, getData, getFunctions, getPluginFunctions, listActions } = config;
 	return {
 		getAction: async (spaceId, actionId, at) => {
 			const found = await config.getAction(spaceId, actionId, at);
@@ -89,14 +93,26 @@ var actionLookupsOf = (config) => {
 			if (!isSpaceFunctions(found)) throw new Error(`The functions of space ${String(spaceId)} are not what @plitzi/sdk-server/functions builds for one`);
 			return found;
 		} } : {},
+		...getData ? { getData: async (spaceId, at) => {
+			const found = await getData(spaceId, at);
+			if (found === void 0 || found === null) return;
+			if (!isProjectData(found)) throw new Error(`The data of space ${String(spaceId)} is not its files' text by path`);
+			return found;
+		} } : {},
+		...getPluginFunctions ? { getPluginFunctions: async (spaceId, at) => {
+			const found = await getPluginFunctions(spaceId, at);
+			if (found === void 0 || found === null) return;
+			if (!isPluginFunctions(found)) throw new Error(`The plugin functions of space ${String(spaceId)} are not, by plugin type, what @plitzi/sdk-server/functions builds for one`);
+			return found;
+		} } : {},
 		...config.getFlags ? { getFlags: config.getFlags } : {}
 	};
 };
 var isFunction = (value) => typeof value === "function";
 /** A driver as `createDbDrivers` builds one: the engine a credential names, and how to query it. */
 var isDbDriver = (value) => isRecord(value) && typeof value.engine === "string" && isFunction(value.query);
-/** The functions config as `@plitzi/sdk-server/functions` builds it: native definitions, a runner, ceilings. */
-var isFunctionsConfig = (value) => isRecord(value) && (value.native === void 0 || Array.isArray(value.native) && value.native.every(isRecord)) && (value.runner === void 0 || isRecord(value.runner) && isFunction(value.runner.describe) && isFunction(value.runner.invoke)) && (value.limits === void 0 || isRecord(value.limits));
+/** The functions config as `@plitzi/sdk-server/functions` builds it: native and plugin definitions, a runner, ceilings. */
+var isFunctionsConfig = (value) => isRecord(value) && (value.native === void 0 || Array.isArray(value.native) && value.native.every(isRecord)) && (value.plugins === void 0 || isRecord(value.plugins) && Object.values(value.plugins).every(isRecord)) && (value.runner === void 0 || isRecord(value.runner) && isFunction(value.runner.describe) && isFunction(value.runner.invoke)) && (value.limits === void 0 || isRecord(value.limits));
 /** The deployment's database drivers, each held to what a `db` task calls — or why one is not, as the server starts. */
 var dbDriversOf = (drivers) => {
 	if (drivers === void 0) return;
@@ -107,7 +123,7 @@ var dbDriversOf = (drivers) => {
 /** The deployment's functions config, held to what runs a space's code — or why it is not, as the server starts. */
 var functionsConfigOf = (config) => {
 	if (config === void 0) return;
-	if (!isFunctionsConfig(config)) throw new Error("`functions` is not what @plitzi/sdk-server/functions configures: `native` definitions, a `runner` with `describe` and `invoke`, `limits`.");
+	if (!isFunctionsConfig(config)) throw new Error("`functions` is not what @plitzi/sdk-server/functions configures: `native` definitions, `plugins` by type, a `runner` with `describe` and `invoke`, `limits`.");
 	return config;
 };
 //#endregion

package/dist/core/createServer.js

@@ -14,7 +14,7 @@ import { createPageServer } from "./server/pageServer.js";
 *  caches or plugin manager this one does. */
 /**
 * Fills in `getRscData` from whatever can produce a server element's data — `connectors`, `action.lookups`, the
-* files of `publicDir` — when the deployment did not write one.
+* files of `dataDir` and `publicDir` — when the deployment did not write one.
 *
 * The lookups are already here and the assembly is entirely this package's — a resolver over `resolveRscData`.
 * Leaving it out meant every deployment passed the same lookups twice: once as config, for the write endpoint,
@@ -25,7 +25,7 @@ import { createPageServer } from "./server/pageServer.js";
 * with no configuration missing anywhere.
 */
 var withConnectorRsc = (config) => {
-	if (config.adapters.getRscData || !config.connectors && !config.action?.lookups && !config.publicDir) return config;
+	if (config.adapters.getRscData || !config.connectors && !config.action?.lookups && !config.publicDir && !config.dataDir) return config;
 	const resolved = {
 		...config,
 		adapters: { ...config.adapters }
@@ -39,6 +39,7 @@ var withConnectorRsc = (config) => {
 		connectors: config.connectors ? connectorLookupsOf(config.connectors) : void 0,
 		actions,
 		publicDir: config.publicDir,
+		dataDir: config.dataDir,
 		elementTimeoutMs: config.rsc?.elementTimeoutMs
 	});
 	return resolved;

package/dist/core/handlers/socialRouteHandlers.js

@@ -60,11 +60,16 @@ var createSocialAuthRouteHandlers = ({ social, cookies, issueSession, onError })
 			* uses: a relative path or an allowed origin is honoured, anything else silently becomes the default. A
 			* missing or unresolved parameter lands on the default too, which is what makes it safe for a template to
 			* pass a token it could not fill in.
+			*
+			* `?fallback=` is where to go instead when `redirect` is refused, vetted by the same judgement — a way BACK
+			* from the screen, whose default ("you are signed in") is the wrong place for somebody who never signed in.
 			*/
 			method: "GET",
 			path: "/continue",
 			handle: (req, res) => {
-				res.redirect(social.sanitizeRedirect(req.query?.redirect));
+				const redirect = req.query?.redirect;
+				const vetted = social.sanitizeRedirect(redirect);
+				res.redirect(vetted === redirect ? vetted : social.sanitizeRedirect(req.query?.fallback));
 				return Promise.resolve();
 			}
 		},

package/dist/core/http/stages/devReload.d.ts

@@ -1,4 +1,5 @@
 import { Stage } from '../types';
+import { PluginEntry } from '@plitzi/sdk-shared';
 /** Where an open page listens for "the space changed: load again", in development. */
 export declare const DEV_RELOAD_PATH = "/__plitzi/reload";
 /**
@@ -8,11 +9,21 @@ export declare const DEV_RELOAD_PATH = "/__plitzi/reload";
  *
  * Only with `devReload` on: every open page keeps a connection for it, which a server that never calls `reloadPages`
  * — a published one, or a platform's — would pay for and get nothing from. The template listens only then too.
+ *
+ * Each connection is greeted with this process's `boot`, and a page that reconnects to a different one loads again: the
+ * server restarted — `start:dev` saw its code change (`main.ts`, its options, its actions, `src/functions/`) — and
+ * what is on screen was built by the one before. Without it the page kept the old plugin until somebody reloaded it,
+ * which reads as "my change did nothing".
  */
 export declare const createDevReload: () => {
     stage: Stage;
     /** Every page open on this server loads again. */
     reload: () => void;
+    /**
+     * A plugin built again: every open page imports its new bundle and swaps it where it is drawn (`keyName` is what
+     * the page registered it as), and points its stylesheet at the new one — without loading again.
+     */
+    plugin: ({ keyName, js, css }: PluginEntry) => void;
     /** The streams ended — the server is going away, and each page reconnects to whichever comes up next. */
     close: () => void;
 };