@plitzi/sdk-server 0.38.5 → 0.38.7

package/CHANGELOG.md

@@ -1,5 +1,223 @@
 # @plitzi/sdk-server
 
+## 0.38.7
+
+### Patch Changes
+
+- c7bbc2b: ## A server project's `src/main.ts` is a few lines
+
+  - **`serveProject` from `@plitzi/sdk-server/project`**: the generated `src/main.ts` hands the space, its actions and
+    its options to the server, and the rest comes with the package — the port, the plugins of `src/plugins` and
+    `vendor/plugins`, the functions and runtime, `public/`, `src/data/`, the `kv` in `state/kv.json`, `/health`,
+    `tmp/dev-server.json` and the reloads while developing. A fix there arrives with `npm update`, not `plitzi upgrade`.
+  - **No more `tmp/space.json` while developing**: a saved space is authored again in its own process and handed to the
+    server over IPC (`plitzi/author.ts --ipc`, in place of `--out`); the server swaps it in memory and the open pages
+    reload, and a refused space keeps the last one that authored. `plitzi doctor` reports a leftover `tmp/space.json`.
+  - **`projectAuthoring()` in `@plitzi/sdk-authoring/node`**: what a project's space is checked against — its plugins'
+    declarations, its built plugins, its data files — once, for the server and `npm run author` alike. Neither it nor
+    `serveProject` takes a root: it is the working directory, where every script runs (`projectAuthoringAt(root)` for a
+    tool working on another folder).
+  - **`authorProjectSpace` and `projectSpace()` in `@plitzi/sdk-authoring/node`**: the project's space read from
+    `src/space/index.ts` — `dist/space/index.js` when the server runs built — once its root and layout are checked, and
+    authored. `src/main.ts` is `serveProject({ space: authorProjectSpace, actions, connectors, serverOptions })`, with no
+    import of the space; `plitzi/author.ts`, the visual tests and the CLI's checks read it the same way. A module that
+    exports no `space` is refused saying what to export (`ProjectSpaceError`).
+  - **`.env` lives at the root and Node reads it** as each script starts (`--env-file-if-exists=.env`; `start:dev`
+    preloads `@plitzi/sdk-server/env`, since a watched process would restart on every change beside the file). Settings
+    read at the top level of `src/config/serverOptions.ts` or the actions are set. Every project gets `.env` and
+    `.env.example`; `plitzi upgrade` removes the old `src/env.ts`.
+  - **One check of a project's layout** (`@plitzi/sdk-shared/project/layout`): a plugin folder with no entry, a
+    JavaScript entry, `src/plugin/` for `src/plugins/`, a `.env` inside `src/`, a space exported by default, a broken
+    `vendor/` plugin… The server refuses to boot listing every error with its fix, `npm run author` and the CLI's checks
+    refuse with the same words, `plitzi doctor` lists them under `layout` and `--fix` makes the ones with a single fix,
+    and `plitzi lint` points at doctor. A plugin folder added broken while developing is reported in the terminal
+    instead of failing in esbuild. Plugins may start at `index.tsx`.
+  - **`createJsonAdapters` serves documents held in memory**: `offlineData` may be a function returning them, not only a
+    path.
+  - **One source for a project's layout**, `@plitzi/sdk-shared/project/paths`; `src/config/serverOptions.ts` is typed
+    `ProjectServerOptions`. `plitzi upgrade files --write` brings an existing project's `main.ts` and `author.ts` up.
+  - **`npm run build` no longer fails on a plugin's stylesheet**: `tsconfig.build.json` includes `plitzi/assets.d.ts`,
+    which a space importing a plugin's declaration reaches through its component.
+
+  ## A write refreshes what shows it
+  - **Writes now refresh server-driven providers.** `runServerAction`, `webHook`, `writeRecord` and the
+    `invalidateQueries` step reach `runtime: 'server'` api containers by id, by `query` URL, or all of them, just as
+    they reach cached browser requests. Before, they reached only the browser's query cache, so a saved write left the
+    page showing the old value until a reload. Hidden providers refresh when they are shown.
+  - **A refresh because something changed asks around every cache.** `performQuery`, writes and invalidations send
+    `Cache-Control: no-cache`; `/_rsc` resolves such a request again instead of serving its cached slice, and keeps the
+    new answer. A `refreshSeconds` timer and a "load more" page still go through the caches.
+  - **`refreshRsc`'s fourth argument is an options object**, `{ location?, fresh? }`.
+
+  ## A space's functions read its data
+  - **`ctx.data('products.json')`** reads one file of the space's data (a project's `src/data/`), parsed and read-only,
+    as of the run's version. Plugins' functions are refused it.
+  - **Self-hosted servers read `dataDir` through the same lookup as the platform**, so `/data/<file>` providers and
+    `ctx.data` read the same files; `plitzi functions dev` reads `src/data`. `/data/../x.json` is now the provider's
+    error state instead of falling through to `publicDir`.
+  - **Importing a file outside `functions/` names the boundary and the fix**: read the space's data with
+    `ctx.data('<file>')`.
+
+  ## Signing in on a self-hosted server
+  - **`createServer({ auth })` tells the pages it renders where to sign in** (`server.auth`: provider, endpoints and
+    the session hint cookie), so a space signs in with no auth settings declared. Settings a space does declare still
+    win, and a space that names another provider ignores the server's description. New `pageAuth` server option, for a
+    deployment whose `/auth` flows are served by another host.
+  - **A page with no auth provider no longer offers `auth.login` / `auth.logout`**, and a sign-in that cannot work says
+    why in the console (`[plitzi] auth.login: …`) instead of failing silently. What a visitor keeps there
+    (`keepState`, `paintedState`) is the browser's, as on any space without accounts: what was kept as a guest's on such
+    a page before is let go once, on the first visit after the upgrade.
+  - **Renewal verifies the refresh token itself.** `findByRefreshToken` no longer has to report `refreshExpiresAt`; when
+    it does, it overrides the token's own expiry.
+  - **New authoring reference `auth.md`**: providers, `authLogin` and its result, `authLogout`, `{{ auth.* }}`,
+    `accessLevel`, visitor roles, action `access` and `ctx.user`.
+
+  ## Flows
+  - **Authoring refuses a `when` that asks a step for a key it never publishes** (`condition-field-unpublished`).
+    `whenSucceeded` / `whenFailed` after `authLogin` always ran the failure branch: they read a server action's
+    `status`. The message names what the step publishes and suggests testing `signedIn.ok` with `when`.
+  - **`explain` lists what a step publishes** (`Reads:`) and finds the auth steps by their builders (`authLogin`,
+    `authLogout`, `authRefreshDetails`). `authLogin({ username, password })` no longer needs `mode`.
+
+  ## Elements
+  - **Images no longer default to a 140×140 square**: they are 140px wide and as tall as their ratio, so `width` or
+    `aspect-ratio` on a class just works. `object-fit` shows in the builder too.
+  - **`formControl` with `subType: 'switch'` renders an on/off switch** (`role="switch"`) — it rendered only its label.
+    Checkboxes and switches show a `true` default or binding as ticked.
+  - **The theme toggle drops the native button look**, and the **`current` style state covers the chosen item of any
+    set**: the link to the page shown, a pressed toggle, a selected tab. The exported `CURRENT_PAGE_SELECTOR` is now
+    `CURRENT_SELECTOR`.
+  - **Element defaults in the style inspector and the MCP catalogue match what the SDK renders**, held by a test. The
+    dialog's `bodyContainer` and `headerCloseButton` slots now reach the page; pagination lays out as declared.
+  - **Markdown takes a class for each part of the document** through its own slot (`heading`, `paragraph`, `link`,
+    `list`, `listItem`, `quote`, `code`, `codeBlock`, `image`, `table`, `anchor`), and `headingLinks: false` drops the
+    link each heading offers to itself while keeping its id, so `/page#anchor` links still work. Its description spells
+    out the HTML it outputs.
+  - **Tabs show every trigger.** The SDK hid every inactive tab item, the header's included, so a set of tabs showed
+    one tab and no way to the others; only the body's panels take turns now.
+  - **A link that names a query is current only on that query**: of `/?window=6h` and `/?window=24h`, the one shown
+    carries `aria-current` — with the path alone, every one of them did. A link with no query is still current on its
+    page whatever the query.
+
+  ## The style language says what `customCss` used to
+  - **Pseudo-elements on a class**: `pseudos: { after: { css: { content: '"→"' }, states: { hover: { … } } } }` —
+    `before`, `after`, `marker`, `placeholder`, `first-letter`, `first-line`, `selection`, each in the class's states and
+    variants. Authoring refuses what draws nothing: a `before`/`after` with no `content`, a `content` without its quotes,
+    a property the browser drops on that pseudo-element.
+  - **Conditions on a class**: `conditions: { 'motion-reduce': { … }, 'container card (max-width: 30rem)': { … } }` —
+    reduced or allowed motion, and container widths, each with its states and pseudo-elements.
+  - **The space's `keyframes`**, validated and written at the top of `customCss`; an `animation-name` no keyframes declare
+    is warned (`animation-name-unknown`).
+  - **New states**: `expanded` (`aria-expanded`), `first`, `last`, `odd`, `even`; the tab panel on show is `current`, and
+    the theme toggle's icon of the scheme in use is `current` on its `icon` slot.
+  - **`ancestors['>']`** is the parent, whatever it wears — a closed component's part reacting to the element around it.
+  - The builder's style inspector, the MCP's definition ops (`pseudos`, `conditions`, and variants with their states) and
+    the export to code read and write all of it; an MCP `patchDefinition` no longer drops what it did not name. Rules in
+    `customCss` a class can hold now — `.link::after`, one under `@media (prefers-reduced-motion: reduce)`, `.row:first-child`,
+    `.row:nth-child(even)`, `.toggle[aria-expanded='true']` — are folded into the class on export and suggested by
+    `custom-css-class`.
+
+  ## Elements take a class for each part
+  - **`formControl`**: `field` (the `<input>` itself), `icon` (the show-password button) and `requiredMark` slots; a switch's
+    knob reads in dark mode and takes `--plitzi-switch-thumb`, `--plitzi-switch-thumb-checked`, `--plitzi-switch-thumb-shadow`.
+  - **`pagination`**: `previous`, `page` (the one shown is its `current` state), `next`, `loadMore`.
+  - **`richText`** and **`markdown`**: a slot per part — `heading` and `heading1`…`heading6`, `strong`, `emphasis`,
+    `divider`, `tableHead`, `tableRow`, `tableHeaderCell`, `tableCell`, and the code block's frame, header, language and
+    copy button. Both heading slots dress one `<h3>`, so `heading-level-overridden` warns when they set the same property
+    and the stylesheet's order makes the general one win. A document is drawn by the SDK's own renderer
+    (`MarkdownDocument` in `@plitzi/sdk-elements`) — plitzi-ui's `Markdown` keeps GitHub's stylesheet for a library's
+    consumers — and reads as a document unstyled: headings, lists, code, tables and quotes get their type from the SDK's
+    base layer, at no weight (`:where()`), so a class on a part's slot replaces what it sets property by property. A
+    `richText` body reads the same.
+  - `custom-css-slot` suggests the slot for a `customCss` rule on a part's SDK class — only where a class on the slot can
+    say the rest of the selector (a state, a pseudo-element); `element-slot-unknown` warns of a slot an element does not
+    have.
+
+  ## Links, refreshes and toasts
+  - **`current: 'section'` on a link** keeps it current on its page and every page under its path (`aria-current="true"`
+    there), styled by the `current` state — no `activeOn` binding for a section.
+  - **A refresh asks only about elements the page shown holds**: a provider on the page being left no longer sends a
+    `/_rsc` about the new address.
+  - **The toasts' parts are `notifications` fields**: `minHeight`, `fontWeight`, `lineHeight`, `iconSize`, `iconGap`,
+    `closeColor`, `closeOpacity`, `progressHeight`.
+  - **A page asked for with its space's token hydrates its own space.** On a host serving many spaces
+    (`?access-token=`), the space document fetched beside the page went without the token, so the host's own space
+    answered it and the browser hydrated another space's document over the page — a hydration error, and its tree
+    rebuilt. The document's address now carries the token the page was asked for with.
+  - **The SDK's stylesheet carries the space's variables from the server's HTML.** It read them from what a provider
+    below it publishes while the page renders, which the server had not done yet when it wrote the sheet; it now
+    resolves them from the document itself (`useResolvedVariables` of `@plitzi/sdk-shared/dataSource/hooks`), the same
+    on both sides.
+  - **A realtime message the pub/sub cannot deliver is answered, not fatal.** A publish that Redis refuses — a timeout under
+    load — is answered `503` with `reason: 'unavailable'`, by the `POST` and in the WebSocket's `ack` alike; a connect,
+    a disconnect or a revoke that fails is logged, on either transport. Each used to reject with nobody waiting, and the server's `unhandledRejection` handler
+    shut the whole process down.
+
+  ## Reporting to Plitzi
+  - **`plitzi feedback`** starts a report of what broke, misled or cost time: it writes the page the report is laid out
+    in (`tmp/feedback/`) with the installed versions, the project and what `doctor` finds already in it, and tells the
+    agent how to fill it — each finding reproduced first, with evidence, impact, workaround and fix, no secrets — and to
+    publish it as an artifact whose link the developer sends. `--previous <url>` continues an earlier report.
+
+  ## Pages that load on every browser
+  - **The import map comes before anything that loads a module**, in the page server's HTML, a published site's
+    (`index.hbs` on the platform), the SDK's and the builder's. React's `modulepreload` links came first, and a browser
+    that had fetched a module already — Chrome before 133 — ignored the map: every bare `import "react"` failed
+    ("Failed to resolve module specifier") and the page never hydrated.
+
+  ## The dev tools
+  - **A page loads the React its dev tools need.** The development build only while the visitor has the dev tools on
+    (shift+F12, within what the deployment allows); turned off, the next load is a production page, React included. It
+    followed the authorization alone, so a space that allowed debugging always shipped development React.
+
+  ## check and lint
+  - **`plitzi check`, `push`, `lint` and `fix` hold the space to what `npm run author` and the server do**: its data
+    files too, so `push` no longer sends a space whose browser provider reads `src/data/` (`server-data-in-browser`).
+  - **`plitzi check` lists each list's rows as drawn and as held in its source** (`feed 4 of 8 rows`,
+    `hits not rendered (16 in its source)`). In `--json`, `lists` is now `{ id: { rendered, source } }`.
+  - **`plitzi check` no longer reports bindings inside a container the page isn't showing**, nor text "in the colour
+    behind it" because of a bar painted over it or a pane that clips it.
+  - **`window.__plitzi.sources()` no longer turns a shared array into `'[…]'`**, and a list row no longer replaces its
+    list's `items`.
+  - **`plitzi lint` says authoring suggestions are quieted with `quiet` on the element**, and reports a
+    `plitzi-lint-disable` comment that names one (`disable-names-suggestion`).
+  - **`plitzi check` says when a page sent the browser elsewhere** (a page for signed-in visitors, to the sign-in) instead
+    of reporting every element missing, and `--as <username>` signs in first through the server's `/auth` routes, the
+    password from `PLITZI_CHECK_PASSWORD`.
+  - **`plitzi upgrade` never replaces @plitzi packages installed locally** — a tarball, a link, a portal, an override: it
+    leaves them and the install, and says which and the command that would install the registry's.
+  - **`plitzi explain` covers every code**: authoring's, `plitzi lint`'s and the project layout's.
+  - **Authoring reads the global sources' fields**: `auth.authenticated` in a condition is refused with "did you mean
+    `isAuthenticated`?" (`global-field-unknown`), and `invalidateElements` must name providers that exist
+    (`element-ids-target`). A template's reads of `computed`, `flags` and the global sources come off the parsed
+    template: a string inside it (`'https://auth.acme.com'`) is no longer read as `auth.acme`.
+  - **`custom-css-notifications` no longer reads the rules `notifications` itself writes** as toasts dressed by hand.
+  - **A refused space or layout is a report, not a stack**: the server's entry point imports the space once the layout is
+    checked, and `npm start` and `npm run author` print every problem and exit with 1.
+  - **New authoring suggestion `class-overrides-class`**: one class's shorthand (`padding`) silently erases a longhand
+    (`padding-top`) another class on the same element writes out.
+
+- Updated dependencies [c7bbc2b]
+  - @plitzi/sdk-shared@0.38.7
+  - @plitzi/plitzi-sdk@0.38.7
+
+## 0.38.6
+
+### Patch Changes
+
+- 3bce653: ## Fixes
+
+  - **The dev tools draw their icons again.** The panel lives in a shadow root of its own, which the page's stylesheets
+    never reach, and Font Awesome moved to a sheet of its own in 0.38.5 (`plitzi-sdk-icons.css`): the badge and every tab
+    lost their icons. The panel now links that sheet inside its root, beside its own. Where it is served is the SDK's
+    new `sdkIconsStylePath` — the page server sends `/sdk-assets/plitzi-sdk-icons.css`, the same sheet the document
+    links — which the `iframe` and `shadow` render modes read too: they had `/plitzi-sdk-icons.css` hard-coded, a path a
+    page server does not serve.
+
+- Updated dependencies [3bce653]
+  - @plitzi/sdk-shared@0.38.6
+  - @plitzi/plitzi-sdk@0.38.6
+
 ## 0.38.5
 
 ### Patch Changes

package/README.md

@@ -162,18 +162,96 @@ runtime, and its files into `public/` — a draft, or any published snapshot (`-
 `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.
 
+## Projects
+
+A project `npx @plitzi/cli create --mode server` writes runs this server through `serveProject`, from
+`@plitzi/sdk-server/project` — its own entry, so a server that is not such a project never loads it. The project's
+`src/main.ts` hands it what is the project's, and `serveProject` wires everything else from where the project keeps it
+(the layout is `@plitzi/sdk-shared/project/paths`'s):
+
+```ts
+import { serveProject } from '@plitzi/sdk-server/project';
+
+import { authorProjectSpace } from '@plitzi/sdk-authoring/node';
+
+import { actions, connectors } from './actions/index.ts';
+import { serverOptions } from './config/serverOptions.ts';
+
+await serveProject({ space: authorProjectSpace, actions, connectors, serverOptions });
+```
+
+`space` is called once the project's root and layout are checked: `authorProjectSpace` reads `src/space/index.ts`'s
+`space` — `dist/space/index.js` when the server runs what `build` emitted (`projectModule` of
+`@plitzi/sdk-shared/project/root`, the rule the runtime is found by too) — and authors it with `projectAuthoring()`. A
+module that exports no `space` is refused saying what to export (`ProjectSpaceError`), and a space that does not author
+with every problem (`SpaceRefusedError`): each printed as the report it is, and the process exits with 1.
+
+The project is the working directory — where every script of its `package.json` runs it, and where a deployment runs
+`node dist/main.js` — never worked out from where a file is: `serveProject` and `authorProjectSpace` refuse to start
+anywhere else, naming what is missing (`package.json`, `src/`; `projectRoot` of `@plitzi/sdk-shared/project/root`, one
+check for both). Its settings are in `process.env` before any module loads: the scripts start Node with
+`--env-file-if-exists=.env`, and no file of the project reads `.env`. `start:dev`, which Node watches, preloads it
+instead — `node --import @plitzi/sdk-server/env --watch-path=… src/main.ts` — since Node, handed an env file under
+`--watch-path`, watches the folder it is in and restarts on every write there: the server's own `tmp/`, from boot.
+
+Both hold the project to its layout before anything else (`assertProjectLayout` of `@plitzi/sdk-shared/project/layout`,
+what `plitzi doctor` says too): a part where the server would read nothing — a plugin folder with no `index.ts` (or
+`index.tsx`), code in `src/plugin/`, `.env` in `src/`, a built plugin with no manifest — stops the boot with every error
+at once (`ProjectLayoutError`, each with its fix; `findings` holds them as data), and what works and should not stay —
+a plugin with no `declaration.ts`, no `.env.example` — is printed while developing, `[layout] …`.
+
+| Option | What it is |
+|---|---|
+| `space` | The space held in the project: a function that authors it — `authorProjectSpace` — called once the project's layout is checked (a save while developing is authored again by `plitzi/author.ts`, in a process of its own). Served from memory; its `warnings` are printed at boot. |
+| `cloud` | Instead of `space`: `{ name }` — the space stays in Plitzi and is read with `createCloudAdapters`, from `PLITZI_HOST_KEY` (required), `PLITZI_ENVIRONMENT` (`main` by default), `PLITZI_REVISION` and `PLITZI_SERVER_URL`. `name` is what `/health` answers with. |
+| `actions`, `connectors` | The space's server actions, found by their id, and the connectors they call. Left out, the server runs no actions. |
+| `serverOptions` | The project's `src/config/serverOptions.ts`, typed `ProjectServerOptions`: what `createServer` takes but for what `serveProject` wires, spread before it — `logLevel` and `logger` (`warn`, to the console; `--verbose` on the command line: `info`), `auth`, `images`, `rsc`, `action.limits`, `action.kv` are the project's to set. |
+
+What it wires from the project:
+
+- **The port.** `PORT`, or 8080 — while developing, the next free one from there (`freePort`). `HOST`, loopback by
+  default (`0.0.0.0` in a container). `PUBLIC_URL` is where people reach it, behind a proxy.
+- **Its plugins.** Every folder of `src/plugins` under its name in camelCase, built from its `index.ts` (or
+  `index.tsx`, `pluginEntry`) and rendered
+  on the server (`action: 'compile'`), with its server half (`functions/`); every plugin of `vendor/plugins`, run as it
+  was built, beside its `plugin-manifest.json` — and the deployment's `pluginNames` naming them all.
+- **Its code.** `src/functions/` (`loadFunctions`), and the space's runtime — `src/runtime/index.ts`, or
+  `dist/runtime/index.js` when the process was started on what `build` emitted (`process.argv[1]` under `dist/`), or
+  `vendor/runtime.bundle` — in this process, its endpoints answered before anything else.
+- **Its files.** `public/` served as it is, `src/data/` read and never served (`dataDir`), the `kv` in `state/kv.json`
+  (`createFileKv`), `PLITZI_SIGNING_SECRET` what `ctx.sign` signs with.
+- **Where it is.** `/health` answers with the space's permanent URL (or the cloud `name`), and `tmp/dev-server.json`
+  records the name, the port and the URL for `plitzi check`, `shot` and `visual`. A signal closes it (`closeOnSignals`).
+
+While developing — `NODE_ENV` other than `production` — `devMode` and `devReload` are on, and:
+
+- **A save to the space is authored again** by the project's `plitzi/author.ts`, in a process of its own (an import is
+  never read twice in one process), run with `--ipc`: it hands the documents back over the IPC channel, the server
+  swaps them in memory and every open page loads again (`reloadPages`). What the script refuses it prints, and the page
+  keeps the last space that authored. A save to the server's own code — `main.ts`, `src/config/`,
+  `src/actions/`, `src/connectors/`, `src/functions/`, `src/runtime/` — is `start:dev`'s to restart on; of a plugin,
+  only its `declaration.ts` is the space's.
+- **A plugin folder added** is registered and the open pages load again; one removed is turned off; a plugin's
+  `functions/` changed is loaded again in place. A plugin's component changed is the server's own `devReload`. A folder
+  it cannot build — no entry yet, a name that is no type — or a `functions/` with no `index.ts` is said in the
+  terminal as the layout check says it (`[plugins] …`, once until it changes), and the server goes on; the folder is
+  registered once it is whole.
+
+It answers `{ server, url, close }`: the `SSRServer`, where it listens, and what stops it — watching, the server and the
+runtime — for a caller that stops it itself.
+
 ## 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.
+options with: a `plitzi create` project keeps them in `src/config/serverOptions.ts`, typed `ProjectServerOptions` — it less
+what `serveProject` wires itself (see [Projects](#projects)).
 
 | 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`) — 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. |
+| `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 `serveProject` does while developing) — 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. |
@@ -187,7 +265,7 @@ wires itself.
 | `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. **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). |
+| `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>`, and a function reads it with `ctx.data(file)` — the space's `getData` when the deployment gives none. 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. |
@@ -206,10 +284,11 @@ wires itself.
 | `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). |
+| `pageAuth` | `Omit<ServerAuth, 'sessionHintCookie'>` | from `auth` | What the rendered pages are told about signing in (`server.auth`): the provider and its endpoints, the hint cookie added per host. Name it when `/auth` is served by another host. |
 | `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. |
+| `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. A page loads React's development build only while its visitor has the dev tools on. |
 | `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. |
@@ -318,7 +397,7 @@ 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
+path, or a function that may answer one — `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`
@@ -326,7 +405,7 @@ path — `saveSchema` and `saveStyle`, each writing its document back into the f
 | 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` | `(spaceId, environment, revision?) => string \| OfflineDataRaw` | Function answering per request: the path for the requested space, or the documents themselves — a process that replaces them while it runs (`serveProject` re-authoring a space). A save to documents it answered is refused: there is no file. |
 | `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. |
@@ -461,12 +540,16 @@ in either runtime — and the page arrives with it. A browser asking for the sam
 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`).
+The data is read through one lookup, `action.lookups.getData(spaceId, at)` — the space's own data as its files' text by
+path, as of the version being rendered or run: what a cloud deployment keeps for a space (`plitzi push`). Given none,
+`createServer` derives it from `dataDir` (its `.json` files, read again once they change), so the folder and the
+platform are read the same way.
 
 `/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.
+list's costs, another visitor's rows — is a server action's to read, answering only what is shown. A function reads
+it with `ctx.data('products.json')` (parsed, read-only, as of the run's version); importing it from `functions/` is
+refused when they are built.
 
 ## Compression
 
@@ -726,7 +809,7 @@ server.plugins.register('my-chart', {
 
 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:
+corner of `kv`, none of the space's credentials, channels or data). This server's own plugins hand theirs over by type:
 
 ```ts
 import { createServer, loadFunctions } from '@plitzi/sdk-server';
@@ -879,7 +962,7 @@ The server automatically registers `GET /_rsc` when `adapters.getRscData` is pro
 }
 ```
 
-**Cache-Control**: `no-store` for the `main` environment; `private, max-age=30` for other environments when `rsc.cacheTtlMs > 0`. Responses also include `X-Cache: HIT` or `X-Cache: MISS` for observability.
+**Cache-Control**: `no-store` for the `main` environment; `private, max-age=30` for other environments when `rsc.cacheTtlMs > 0`. Responses also include `X-Cache: HIT` or `X-Cache: MISS` for observability. A request sent with `Cache-Control: no-cache` is resolved again rather than read from the cache, and its answer replaces the cached one — the SDK sends it for a refresh that exists because something changed (a write, `invalidateQueries`, `performQuery`); a `refreshSeconds` timer goes through the cache.
 
 The endpoint returns `400` if `spaceId` is missing or invalid, `500` if `getRscData` throws, and `501` if the adapter is not configured.
 
@@ -952,7 +1035,10 @@ which meant the ordinary deployment went without, because nobody configures what
 `api.rateLimit` to put one counter behind a fleet.
 
 `auth` on the server is the whole of the wiring: it mounts the `/auth` flows, answers the identity adapters a page
-server asks for, and carries the cookie naming with it — so there is no second place to keep in step. Everything is
+server asks for, and carries the cookie naming with it — so there is no second place to keep in step. It also tells
+every page it renders where it signs in (`server.auth`: `userProvider: 'basic'`, `loginUrl`, `userUrl`, `logoutUrl`,
+`refreshUrl` and `mfaUrl` where offered, and `sessionHintCookie` named for the host), so the space declares nothing. A
+setting the space does declare wins, and a space that names another provider ignores the server's altogether. Everything is
 still exported separately (`createTokens`, `createIdentity`, `createAuthApi`, `authRoutes`, …) for a deployment that
 wants to assemble or replace one piece.
 
@@ -1011,7 +1097,7 @@ Postgres, MySQL, Mongo or an identity service:
 | `clearSession(target)` | signing out |
 | `loadAccess(userId)` | the roles and permissions a grant answers with |
 | `findByUsername(username)` | password sign-in |
-| `findByRefreshToken(token)` | renewal. Answer with `refreshExpiresAt`, or every renewal is refused as expired |
+| `findByRefreshToken(token)` | renewal — the row is its revocation switch. `refreshExpiresAt` overrides the token's own expiry |
 | `findMembership(userId, spaceId)` | space-level permission checks (`auth.can`) |
 | `createAccount`, `findByEmail`, `setResetToken`, `sendMail`, … | signup, password reset, verification |
 

package/dist/adapters/jsonAdapters.d.ts

@@ -5,11 +5,15 @@ import { OfflineDataRaw, SSRPageAdapters, SSRSpaceDeployment } from '@plitzi/sdk
  */
 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 `saveSchema` and `saveStyle` are offered only when one was given.
+     * The space: a path to a `{ schema, style }` JSON, the data itself for a consumer that already holds it (composed at
+     * startup, fetched once, built in a test), or a function answering either per request — a path per space, or the
+     * documents a process holds and replaces while it runs (a project re-authoring its space on a save). Only a path can
+     * be written back to: `saveSchema` and `saveStyle` are not offered for the data itself, and refuse a function's
+     * answer that is not a path.
      */
-    offlineData: OfflineDataRaw | string | ((spaceId: number, environment: string, revision?: number) => string);
+    offlineData: OfflineDataRaw | string | OfflineDataSource;
     deployment?: string | SSRSpaceDeployment | Record<string, SSRSpaceDeployment>;
 };
+/** Where the space a request asks for is: a JSON file's path, or the documents themselves. */
+export type OfflineDataSource = (spaceId: number, environment: string, revision?: number) => string | OfflineDataRaw;
 export declare const createJsonAdapters: (config: JsonAdaptersConfig) => SSRPageAdapters;

package/dist/adapters/jsonAdapters.js

@@ -24,15 +24,11 @@ var createJsonReader = () => {
 };
 var createJsonAdapters = (config) => {
 	const json = createJsonReader();
-	const pathFor = (spaceId, environment, revision) => {
-		if (typeof config.offlineData === "function") return config.offlineData(spaceId, environment, revision);
-		return typeof config.offlineData === "string" ? config.offlineData : void 0;
-	};
+	const sourceFor = (spaceId, environment, revision) => typeof config.offlineData === "function" ? config.offlineData(spaceId, environment, revision) : config.offlineData;
 	const getOfflineData = (spaceId, environment, revision) => {
 		try {
-			const filePath = pathFor(spaceId, environment, revision);
-			if (!filePath) return Promise.resolve(config.offlineData);
-			return Promise.resolve(json.read(filePath));
+			const source = sourceFor(spaceId, environment, revision);
+			return Promise.resolve(typeof source === "string" ? json.read(source) : source);
 		} catch (err) {
 			serverLog.error("JsonAdapters", "Failed to read offlineData", err);
 			return Promise.resolve(void 0);
@@ -41,8 +37,8 @@ var createJsonAdapters = (config) => {
 	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();
+		const filePath = sourceFor(spaceId, environment);
+		if (typeof filePath !== "string") return Promise.reject(/* @__PURE__ */ new Error(`Space ${String(spaceId)} (${environment}) is held in memory, not in a file: there is nowhere to save it.`));
 		const current = json.read(filePath);
 		writeFileSync(filePath, JSON.stringify({
 			...current,

package/dist/core/auth/api.d.ts

@@ -17,7 +17,10 @@ export interface AccountRecord {
     verified: boolean;
     /** Absent for accounts that have no password — one created through an identity provider, for instance. */
     passwordHash?: string;
-    /** Unix seconds, for the refresh credential this account currently holds. */
+    /**
+     * Unix seconds the refresh credential being renewed dies at, reported by `findByRefreshToken` — an override: left
+     * out, the credential's own expiry decides.
+     */
     refreshExpiresAt?: number;
     /**
      * Unix seconds the session being renewed BEGAN, for `lifetimes.session` — the cap on how long one may live

package/dist/core/auth/api.js

@@ -3,7 +3,7 @@ import { forwardedIp } from "../requestParser.js";
 import { checkPermission } from "./authorize.js";
 import { generateToken, hashPassword, verifyPassword } from "./passwords.js";
 import { createMemoryRateLimit, fleetRateLimit } from "./throttle.js";
-import { authFailureMessage } from "./tokens.js";
+import { authFailureMessage, userIdOf } from "./tokens.js";
 import { generateRecoveryCodes, generateTotpSecret, normalizeRecoveryCode, randomCode, totpStep, totpUri } from "./totp.js";
 import { createHash } from "node:crypto";
 //#region src/core/auth/api.ts
@@ -705,14 +705,23 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 			if (!refreshToken) return refuse(400, "Refresh token is required");
 			/**
 			* Every refusal below ends the session in this browser, because each of them means the credential it just
-			* presented can never work again: no such row, past its deadline, or an account that may not hold one. What
-			* is being cleared is not authority — the row is already gone — it is the browser's reason to keep asking.
+			* presented can never work again: not one this deployment signed, no such row, past its deadline, or an
+			* account that may not hold one. What is being cleared is not authority — the row is already gone — it is the
+			* browser's reason to keep asking.
+			*
+			* The token carries its own deadline, so the store is asked only whether it still holds the row — the switch
+			* that revokes it. A `refreshExpiresAt` it reports overrides that deadline, and a store that keeps none needs
+			* to report nothing.
 			*/
-			const account = await adapters.findByRefreshToken?.(refreshToken);
-			if (!account || !account.refreshExpiresAt || account.refreshExpiresAt < Math.floor(Date.now() / 1e3)) return {
+			const lapsed = {
 				...refuse(401, "Invalid or expired refresh token", "expired"),
 				endSession: true
 			};
+			const verified = tokens.verifyRefreshToken(refreshToken);
+			if (!verified.ok) return lapsed;
+			const account = await adapters.findByRefreshToken?.(refreshToken);
+			const deadline = account?.refreshExpiresAt ?? verified.payload.exp;
+			if (!account || account.id !== userIdOf(verified.payload) || deadline === void 0 || deadline < now()) return lapsed;
 			if (!account.active) {
 				const reason = deniedReason(account);
 				return {

package/dist/core/auth/createAuth.d.ts

@@ -4,7 +4,7 @@ import { CredentialCarrier } from './credentials';
 import { IdentityAdapters, IdentityConfig } from './identity';
 import { CookieSink } from './session';
 import { TokenConfig } from './tokens';
-import { SSRAuthCookie, SSRSession, SSRUser } from '@plitzi/sdk-shared';
+import { ServerAuth, SSRAuthCookie, SSRSession, SSRUser } from '@plitzi/sdk-shared';
 /**
  * Everything a deployment says about its own auth, in one object.
  *
@@ -187,6 +187,12 @@ export declare const createAuth: (config: AuthConfig) => {
     /** Where these flows were mounted, so whatever serves them reads it here rather than defaulting to `/auth`
      *  on its own — a host that guessed would serve the routes somewhere the policy above does not guard. */
     basePath: string;
+    /**
+     * What a page server tells the pages it renders about these flows (`server.auth`), so a space signs in here with
+     * nothing to declare: the HTTP+JSON shape the SDK's `basic` provider speaks, at this `basePath`, with renewal and
+     * the second factor only where this deployment offers them.
+     */
+    pageAuth: Omit<ServerAuth, "sessionHintCookie">;
     /** The naming this was built with, so a page server takes it from here instead of being told a second time. */
     cookieConfig: SSRAuthCookie | undefined;
     /**

package/dist/core/auth/createAuth.js

@@ -54,6 +54,14 @@ var createAuth = (config) => {
 		}
 	});
 	const basePath = config.basePath ?? "/auth";
+	const pageAuth = {
+		userProvider: "basic",
+		loginUrl: `${basePath}/login`,
+		userUrl: `${basePath}/session`,
+		logoutUrl: `${basePath}/logout`,
+		...api.capabilities.refresh ? { refreshUrl: `${basePath}/refresh` } : {},
+		...api.capabilities.mfa ? { mfaUrl: `${basePath}/mfa/complete` } : {}
+	};
 	const policy = {
 		rules: [...config.rules ?? [], ...authPolicyRules(basePath)],
 		fallback: config.fallback ?? "actor"
@@ -117,6 +125,12 @@ var createAuth = (config) => {
 		/** Where these flows were mounted, so whatever serves them reads it here rather than defaulting to `/auth`
 		*  on its own — a host that guessed would serve the routes somewhere the policy above does not guard. */
 		basePath,
+		/**
+		* What a page server tells the pages it renders about these flows (`server.auth`), so a space signs in here with
+		* nothing to declare: the HTTP+JSON shape the SDK's `basic` provider speaks, at this `basePath`, with renewal and
+		* the second factor only where this deployment offers them.
+		*/
+		pageAuth,
 		/** The naming this was built with, so a page server takes it from here instead of being told a second time. */
 		cookieConfig: config.cookie,
 		/**

package/dist/core/auth/credentials.d.ts

@@ -20,6 +20,8 @@ export declare const readCookies: (carrier: CredentialCarrier) => Record<string,
  * both and the typed verifier decides which it actually is — that is what `scope` is for. Trying the wrong kind
  * costs nothing: it fails on its scope claim before any database is touched.
  */
+/** The query parameter a space token rides in: how a page on a host serving many spaces names the one it is. */
+export declare const SPACE_TOKEN_PARAM = "access-token";
 export declare const createCarriers: (sessionCookieName: (hostname: string) => string) => {
     userTokenCandidates: (carrier: CredentialCarrier) => string[];
     spaceTokenCandidates: (carrier: CredentialCarrier) => string[];

package/dist/core/auth/credentials.js

@@ -23,6 +23,8 @@ var unique = (candidates) => [...new Set(candidates.filter(Boolean))];
 * both and the typed verifier decides which it actually is — that is what `scope` is for. Trying the wrong kind
 * costs nothing: it fails on its scope claim before any database is touched.
 */
+/** The query parameter a space token rides in: how a page on a host serving many spaces names the one it is. */
+var SPACE_TOKEN_PARAM = "access-token";
 var createCarriers = (sessionCookieName) => ({
 	userTokenCandidates: (carrier) => unique([
 		headerValue(carrier.headers["plitzi-access-token"]),
@@ -30,7 +32,7 @@ var createCarriers = (sessionCookieName) => ({
 		readCookies(carrier)[sessionCookieName(carrier.hostname)] ?? ""
 	]),
 	spaceTokenCandidates: (carrier) => {
-		const queryToken = carrier.query?.["access-token"];
+		const queryToken = carrier.query?.[SPACE_TOKEN_PARAM];
 		return unique([
 			headerValue(carrier.headers["x-access-token"]),
 			bearer(carrier),
@@ -51,4 +53,4 @@ var createCarriers = (sessionCookieName) => ({
 */
 var presentedOrigin = (carrier) => headerValue(carrier.headers.origin);
 //#endregion
-export { createCarriers, presentedOrigin, readCookies };
+export { SPACE_TOKEN_PARAM, createCarriers, presentedOrigin, readCookies };